Extern/OxySec/Include/xlt.h

/** 
\file
\page xlt_library XLight Library Documentation
 * 
 * 

// \note
> <span style="color:rgb(216,16,16); font-size:18px"><b>This is the reference manual for the XLight APIs.<BR>
> Before reading this document it is strongly recommended to see the following documentation:</b></span>
> <ul>
> <li><a href="https://sites.google.com/a/oxysec.com/xlight-tech-eng/xlight" target="_blank"><b><i>Online XLight documentation</i></b></a>
> </ul> 
> <i>To access these links it is necessary that <b>OxySec</b> has enabled a <b>Google account</b> of yours with due permissions. Ask <b>OxySec</b> what to do if you haven't such permission.</i>


<BR>
\note This documentation is related to the original APIs for XLight, at present it is still possible call all these functions
 from the xNodus dll, alternatively it is possible (and preferred) to use the \ref xnd_xlt_functions "porting of all these functions".

<p>
This is the documentation of the \ref xltapi_old "APIs" for the communication between the host computer and the XLight device.

This documentation is extracted from the original XLight documentation, now it is part of the \ref xnd_mainpage "xNodus project".


<P>
<P>
\section adv_topics Advanced topics

Read the following topics on Advanced XLight protection


<ul>
<li> \subpage locked_memory
<li> \subpage RSA_Protection
<li> \subpage AES_Session_Key
<li> \subpage SDMEM
<li> \subpage TIMER_COUNTERS
<li> \subpage DATE_LICENSING
</ul>
*/

/** \defgroup xltapi_old XLight APIs (old version)
Api functions for the communication between one or more XLight devices and the host PC.

Every function is almost thread safe. Here 'almost' means that the functions are thread safe with the following exceptions:
<ol>
<li> xlt_close() is not thread safe.
<li> The first api call is not thread safe, that is the first call makes the library to run its inner context initialization. 
This is not a thread safe operation. This operation is done only from the first call, so all subsequent calls may be done 
concurrently (except xlt_close()) from different threads.
<li> Concurrency is (almost) always technically possible, and the USB communication is queued,
but it must be done with care: for instance run concurrently instances of xlt_write_locked() on the same device will lead to an error (the second call will fail).
Accessing different devices can be done without any concerns.
</ol>

The APIs can be used simultaneously also by different processes communicating with the same device and the consideration '3' above holds as well.

@{
	\defgroup xlt_device Device Management
	@{
		\defgroup xlt_ss XLight sessions
		@{
		@}

		\defgroup xlt_adv Advanced functions
		@{
		@}

	@}


	\defgroup xlt_bank Memory Banks Managemement
	@{
	@}

	\defgroup xlt_aes AES session keys
	@{
	@}

	\defgroup xlt_rsa RSA
	@{
	@}

	\defgroup xlt_tc Timer and Counters
	@{
		\defgroup xlt_tc_struct Timer and Counters structures
		Data structures and defines for the management of the XLight timer and counters.
		@{
		@}

		\defgroup xlt_timer Timer
		@{
		@}

		\defgroup xlt_counter Counter
		@{
		@}
	@}

	\defgroup xlt_date Date
	@{
		\defgroup date_str Date structures
		Data structures and defines for the management of the XLight time based license management.
		@{
		@}

	@}

	\defgroup xlt_sd SD Storage
	@{
	@}

	\defgroup xlt_defines XLight defines
	Constants used by the \ref xltapi_old functions.
	@{
	@}
@}

*/


#ifndef XLT_H_205672482
#define XLT_H_205672482

#ifdef USE_BCC_502
#define USE_BCC
#endif

// We don't use "unsigned long long" because Borland C doesn't recognize it, while "unsigned __int64" works both in Borland and Microsoft Visual Studio
/**
an alias for unsigned __int64
*/

#ifdef __LP64__ //MAC
#define XLT_ULONG_LONG unsigned long long
#else //__LP64__
#define XLT_ULONG_LONG unsigned __int64
#endif //__LP64__


#ifdef __cplusplus
extern "C" {
#endif

/** \defgroup xlt_comp Compiler options
\ingroup xlt_defines
@{
 * Linking and calling convention specifications for the current compiler.
 */
#define XLT_LINK ///< Linking type of the exported XLight functions.
#ifdef __LP64__ //MAC
#define XLT_API
#else //MAC
#define XLT_API __stdcall ///< Calling convention of the exported XLight functions.
#endif //MAC
//@}


//\cond NOT_COMMENTED
#ifndef OPT
#define OPT
#endif
//\endcond

/** \defgroup Flags Flags
 * \ingroup xlt_defines
 * Flag codes.
 * Flags returned by the xlt_getinfo() function. They are returned as a mask of bits: for instance the returned value 0x110 means that the XLight device
 * has XLT_FLAG_SETUP and  XLT_FLAG_FROZEN_BANK0 set, that is the label is configured (already setup), and the memory bank 0 is frozen (i.e. it can't be rewritten).
 //@{
 */
#define XLT_FLAG_SETUP 0x10 ///< Set if the device has been initialized.
#define XLT_FLAG_FROZEN_BANK0 0x0100 ///< Set if the bank 0 is frozen (no longer writable)
#define XLT_FLAG_FROZEN_BANK1 0x0200 ///< Set if the bank 1 is frozen (no longer writable)
#define XLT_FLAG_FROZEN_BANK2 0x0400 ///< Set if the bank 2 is frozen (no longer writable)
#define XLT_FLAG_FROZEN_BANK3 0x0800 ///< Set if the bank 3 is frozen (no longer writable)
#define XLT_FLAG_FROZEN_BANK4 0x1000 ///< Set if the bank 4 is frozen (no longer writable)
#define XLT_FLAG_FROZEN_BANK5 0x2000 ///< Set if the bank 5 is frozen (no longer writable)
#define XLT_FLAG_FROZEN_BANK6 0x4000 ///< Set if the bank 6 is frozen (no longer writable)

#define XLT_FLAG_LOCKED_BANK0 0x010000 ///< Set if the bank 0 is locked (writable only in encryption form)
#define XLT_FLAG_LOCKED_BANK1 0x020000 ///< Set if the bank 1 is locked (writable only in encryption form)
#define XLT_FLAG_LOCKED_BANK2 0x040000 ///< Set if the bank 2 is locked (writable only in encryption form)
#define XLT_FLAG_LOCKED_BANK3 0x080000 ///< Set if the bank 3 is locked (writable only in encryption form)
#define XLT_FLAG_LOCKED_BANK4 0x100000 ///< Set if the bank 4 is locked (writable only in encryption form)
#define XLT_FLAG_LOCKED_BANK5 0x200000 ///< Set if the bank 5 is locked (writable only in encryption form)
#define XLT_FLAG_LOCKED_BANK6 0x400000 ///< Set if the bank 6 is locked (writable only in encryption form)

#define XLT_FLAG_TYPE_LOCK 0x800000 ///< Indicate the type of lock applied: if set to 1 the Lock2 is set
//@} // Flags

/** \defgroup Models XLight Models
 * \ingroup xlt_defines
 * \ingroup xlt_device
 * Model codes.
 * These are the possible model codes returned by the xlt_getinfo() function. At present there is only one possible value.
 @{
 */
#define XLT_MODEL_BASIC_USBHID 0x0 ///< Device using the USB DriverLess protocol (HID). It doesn't require a kernel driver.
#define XLT_MODEL_USBHID_SD 0x1 ///< Device using the USB DriverLess protocol (HID) supplying also an interface for Micro SD reader
//@} // Models

/** \defgroup Sizes XLight constants sizes
 * \ingroup xlt_defines
 * Sizes in bytes of the buffers passed to and retrieved from the XLight APIs, plus other XLight consts.
 @{
 */
#define XLT_LABEL_SIZE 64 ///< Size of the Label field passed to the xlt_getinfo() and xlt_setup() functions.
#define XLT_PASSWORD_SIZE 32 ///< Size of the password field.
#define XLT_KEY_SIZE 32 ///< Size of a cryptographic Key.
#define XLT_BANK_SIZE 64 ///< Size of each bank of memory of the XLight device.
#define XLT_NUMBER_OF_BANKS 7 ///< Number of memory banks of the XLight device.
#define XLT_LOCKED_BANK_DATA_LENGTH 48 ///< Portion of the usable data for a locked bank. The rest of the bank is used for internal purpose.
#define XLT_LOCKED_TRANSFER_DATA 80 ///< data to be passed or retrieved using xlt_write_locked() and xlt_read_locked() 
#define XLT_CIPHERTEXT_SIZE 16 ///< Size of the plaintext and ciphertext passed or retrieved by the crypto functions (xlt_encrypt(), xlt_decrypt() and xlt_challenge())
#define XLT_DEVICE_MAX 16 ///< Max number of XLight devices. Useful when scanning all the device with the xlt_getinfo() functions.
#define XLT_SESSION_NUMBER_OF_KEYS 8 ///< Number of AES Session Keys

#define XLT_DEVICE_EXT_MAX (XLT_DEVICE_MAX + 1) ///< Max number of XLight and xNodus devices. Useful when scanning all the device with the xlt_getinfo() functions. (only one xNodus device can be addressed using original APIs)

//#define XN_FIRST_MODULE_INDEX 0 ///< QQQQ
//#define XN_LAST_MODULE_INDEX 64 ///< QQQQ

#define XLT_RSA_512_BIT_SIZE 512 ///< length in bit of the public modulus of a 512 bit RSA key
#define XLT_RSA_512_WRAPPED_KEY_SIZE 144 ///< dimension of an RSA private key with modulus of 512 bit in its wrapped form
#define XLT_RSA_512_PUB_KEY_SIZE 68 ///< dimension of an RSA public key with modulus of 512 bit
#define XLT_RSA_512_PRIV_KEY_SIZE 132 ///< dimension of an RSA private key with modulus of 512 bit
#define XLT_RSA_512_PLAINTEXT_SIZE 64 ///< dimension of a plaintext for a 512 bit RSA key
#define XLT_RSA_512_CIPHERTEXT_SIZE XLT_RSA_512_PLAINTEXT_SIZE ///< dimension of a ciphertext for a 512 bit RSA key

#define XLT_RSA_1024_BIT_SIZE 1024 ///< length in bit of the public modulus of a 1024 bit RSA key
#define XLT_RSA_1024_WRAPPED_KEY_SIZE 272 ///< dimension of an RSA private key with modulus of 1024 bit in its wrapped form
#define XLT_RSA_1024_PUB_KEY_SIZE 132 ///<dimension of an RSA public key with modulus of 1024 bit
#define XLT_RSA_1024_PRIV_KEY_SIZE 260 ///< dimension of an RSA private key with modulus of 1024 bit
#define XLT_RSA_1024_PLAINTEXT_SIZE 128 ///< dimension of a plaintext for a 1024 bit RSA key
#define XLT_RSA_1024_CIPHERTEXT_SIZE XLT_RSA_1024_PLAINTEXT_SIZE ///< dimension of a ciphertext for a 1024 bit RSA key

#define XLT_DISK_PASSWORD_SIZE 32 ///< Size of the disk password (used onto to sd devices).
#define XLT_COUNTERS_NUM 4 ///< number of usable counters in XLight
//@} // Sizes


/** \defgroup xlt_Errors Errors Code
 * \ingroup xlt_defines
 * Error codes.
 * The XLight functions return the following error codes.
 @{
 */
#define XLT_ERROR_SUCCESS 0 ///< the operation was successfully completed  
#define XLT_ERROR_NOT_FOUND -1 ///< Device not found.
#define XLT_ERROR_INVALID_ARGUMENT -2 ///< Function called with an invalid argument.
#define XLT_ERROR_INVALID_STATE -3 ///< Invalid state of the device for the required operation.
#define XLT_ERROR_TRANSMIT -4 ///< USB communication error.
#define XLT_ERROR_RESOURCE -5 ///< Resource error (usually not enough memory).
#define XLT_ERROR_WRONG_PSWD -6 ///< A wrong password has been used
#define XLT_ERROR_MISSING_DATA -7 ///< Missing data (returned by an attempt to read memory from an unwritten bank)
#define XLT_ERROR_FROZEN -8 ///< Trying to write or freeze a frozen bank
#define XLT_ERROR_LOCKED -9 ///< Trying to lock an already locked bank
#define XLT_ERROR_LOCKED_BAD_SERIAL -10 ///< Writing in a locked bank passing a wrong serial
#define XLT_ERROR_LOCKED_BAD_COUNTER -11 ///< Writing in a locked bank passing a wrong counter
#define XLT_ERROR_LOCKED_BAD_GROUP -12 ///< Writing in a locked bank passing a wrong group number
#define XLT_ERROR_RSA_MAN -13 ///< An error occurred running an RSA software function
#define XLT_ERROR_ENC_DISK_NOT_EXIST -14 ///< Error on <i>XLight SD</i> trying to mount the non existent encrypted disk
#define XLT_ERROR_STOPPED -15 ///< The function was stopped by the timer, counter or date protection management
#define XLT_ERROR_TC_BAD_SERIAL -16 ///< Attempting to apply a time-counter setting on a device with unexpected serial number
#define XLT_ERROR_TC_BAD_FORMAT -17 ///< Bad timer-counter command or data format (for instance a wrong <i>Dongle Key</i> was used)
#define XLT_ERROR_TC_BAD_CMD_COUNTER -18 ///< The counter of the time-counter command was wrong (probably the command was already been applied)
#define XLT_ERROR_TC_BAD_VALUE -19 ///< Wrong timer or conter value, it's value exceed the allowed limit 
#define XLT_ERROR_DATE_BAD_SERIAL -20 ///< Attempting to apply a date setting on a device with unexpected serial number
#define XLT_ERROR_DATE_BAD_FORMAT -21 ///< Bad date command or data format (for instance a wrong <i>Dongle Key</i> was used)
#define XLT_ERROR_DATE_BAD_CMD_COUNTER -22 ///< The counter of the date command was wrong (probably the command was already been applied)
#define XLT_ERROR_DATE_BAD_VALUE -23 ///< sent a date older than the one extimated by the device
#define XLT_ERROR_DATE_STOPPED -24 ///< The function was stopped by the date protection management
#define XLT_ERROR_DATE_NOT_CONFIGURED -25 ///< Date management not configured
#define XLT_ERROR_DATE_BAD_CHALLENGE -26 ///< Bad challenge value (value not expected)
#define XLT_ERROR_DATE_CHALLENGE_TIME_OUT -27 ///< The signed data was sent after challenge expiration
#define XLT_ERROR_DATE_UNUSED_SIGNED_TIME -28 ///< A signed date is not expected by the device
#define XLT_ERROR_RSA_INTERNAL_ERROR -29 ///< An internal error occurred running the RSA algorithm (it should never happen)

#define XLT_ERROR_DATEMAN_EXPIRED -30 ///< date license expired
#define XLT_ERROR_DATEMAN_TIME_SOURCE_UNAVAILABLE -31 ///< any attempt to get a date (local or form internet) is failed
#define XLT_ERROR_DATEMAN_INTERRUPTED -32 ///<date management function was abruptly interrupted
#define XLT_ERROR_DATEMAN_IS_RUNNING -40 ///< the date management thread is (already) running and the called function can't be done
#define XLT_ERROR_DATEMAN_NOT_RUNNING -41 ///< the date management thread is not running
#define XLT_ERROR_DATEMAN_NOT_SUPPORTED -42 ///< the XLight device doesn't support date license or date license is not set
#define XLT_ERROR_DATEMAN_PENDING -43 ///< the date management is pending (that is it is running and the task is not completed yet)

#define XLT_ERROR_DATEMAN_NTP_UNAVAILABLE -52 ///< the NTP server is not found (the address is wrong or cannot be resolved or the internet connection is down)
#define XLT_ERROR_DATEMAN_NTP_INCONSISTENT -53 ///< the collected NTP time is wrong
#define XLT_ERROR_DATEMAN_NTP_INTERNAL_ERROR -54 ///< an error occurred managing the NTP time acquiring process
#define XLT_ERROR_DATEMAN_NTP_LOW_TIME_QUALITY -55 ///< the quality of the NTP time is not good enough

#define XLT_ERROR_DATEMAN_HTTP_INTERNAL_ERROR -60 ///< an internal error happened collecting the signed time
#define XLT_ERROR_DATEMAN_HTTP_GENERIC_ERROR -61 ///< a generic error happened collecting the signed time
#define XLT_ERROR_DATEMAN_HTTP_INVALID_URL -62 ///< invalid URL of the signed time server
#define XLT_ERROR_DATEMAN_HTTP_CANNOT_CONNECT -63 ///< impossible to establish a connection with the signed time server
#define XLT_ERROR_DATEMAN_HTTP_CONNECTION_ERROR -64 ///< the connection to the signed time server failed
#define XLT_ERROR_DATEMAN_HTTP_TIMEOUT -65 ///< timeout of the connection to the signed time server 
#define XLT_ERROR_DATEMAN_HTTP_MISSING_DATA -66 ///< same expected data was missing during a communication with the signed time server

#define XLT_ERROR_SESSION_NO_ACTIVE_SESSION -70 ///< There is no active session
#define XLT_ERROR_SESSION_INVALID_SESSION -71 ///< Invalid session value
#define XLT_ERROR_SESSION_UNEXPECTEDLY_CLOSED -72 ///< a session was closed in an expected way (also unplugging the device)
#define XLT_ERROR_SESSION_NO_ACTIVE_SW_SESSION -73 ///< There is no active session at API level

#define XLT_ERROR_RSA_WRONG_SN -80 ///< the wrapped RSA key was prepared for an XLight device with a different serial number

#define XLT_ERROR_UNKNOWN -100 ///< an unknown error has occurred

#define XLT_ERROR_MODULE_INACTIVE -110 ///< the module is not active (it is not available)
#define XLT_ERROR_MODULE_ALREADY_OPEN -111 ///< already open module
#define XLT_ERROR_MODULE_ALREADY_CLOSED -112 ///< already closed module
#define XLT_ERROR_MODULE_INVALID_COUNTER -113 ///< the counter of the module setting command is not valid
#define XLT_ERROR_MODULE_INVALID_INDEX -114 ///< the index module doesn't exist
#define XLT_ERROR_MODULE_NOT_OPEN -115 ///< the module is not open
#define XLT_ERROR_MODULE_INVALID_KEY_TYPE -116 ///< the key type for module verification is invalid
#define XLT_ERROR_MODULE_BAD_PADDING -117 ///< padding check error during module setting (xnd_xlt_config_modules_apply()) or key for module check setting (xnd_xlt_set_modules_key_apply())
#define XLT_ERROR_MODULE_INVALID_COMMAND -118 ///< invalid command check error during module setting (xnd_xlt_config_modules_apply()) or key for module check setting (xnd_xlt_set_modules_key_apply())


//@} // xlt_errors

//\cond NOT_COMMENTED
#define XLT_ERROR_INVALID_FW_RELEASE -1050
#define XLT_ERROR_INVALID_SN -1051
#define XLT_ERROR_INVALID_B_COUNTER -1052
//\endcond



/** \struct _XLT_TIMER_DATA
\ingroup xlt_tc_struct
The structure contains the data of the XLight timer.
*/
struct _XLT_TIMER_DATA{
	XLT_ULONG_LONG functions_to_lock_mask;///< bits masks of the functions that won't work after timer expiration. This mask is built making a birwise or of the values from \ref Lock_mask.
	unsigned int timer_value_minutes;///< current value of the timer expressed in minutes, when this value is used in a command this is the starting value of the timer.
	unsigned int idle_time_minutes; ///< idle time before stopping the timer countdown expressed in minutes. After <i>idle_time_minutes</i> of inactivity of the XLight device the countdown process is suspended. It will be resumed at the first access to the dongle.
	unsigned int cmd_counter;///< strictly increasing value used to avoid command replication. If the data is retrieved this is the last value used for this field. 
	unsigned int serial_number;///< the serial number of the referred XLight device
};

/** \typedef XLT_TIMER_DATA
\ingroup xlt_tc_struct
\see ::_XLT_TIMER_DATA
*/
typedef struct _XLT_TIMER_DATA XLT_TIMER_DATA;

/** \struct _XLT_TIMER_ADD_CMD
\ingroup xlt_tc_struct
The structure contains the command for incrementing the timer.
*/
struct _XLT_TIMER_ADD_CMD{
	unsigned int timer_value_minutes_to_add;///< minutes to add to the current value of the timer
	unsigned int cmd_counter;///< strictly increasing value used to avoid command replication. If the data is retrieved this is the last value used for this field
	unsigned int serial_number;///< the serial number of the referred XLight device
}; 

/** \typedef XLT_TIMER_ADD_CMD
\ingroup xlt_tc_struct
\see ::_XLT_TIMER_ADD_CMD
*/
typedef struct _XLT_TIMER_ADD_CMD XLT_TIMER_ADD_CMD;

/** \struct _XLT_COUNTER_DATA
\ingroup xlt_tc_struct
The structure contains the data of an XLight counter.
*/
struct _XLT_COUNTER_DATA{
	XLT_ULONG_LONG trigger_functions_mask;///< mask of the functions that causes the counter to be decremented. This mask is built making a birwise or of the values from \ref Trigger_mask.
	XLT_ULONG_LONG functions_to_lock_mask;///< functions that won't work after counter expiration (reached 0). This mask is built making a birwise or of the values from \ref Lock_mask.
	unsigned int counter_id;///< address the counter (it may take 0, 1, 2 or 3).
	unsigned int counter_value;///< starting value for the counter (or current value if retriving data)
	unsigned int cmd_counter;///< strictly increasing value used to avoid command replication. If the data is retrieved this is the last value used for this field
	unsigned int serial_number;///< the serial number of the referred XLight device
};

/** \typedef XLT_COUNTER_DATA
\ingroup xlt_tc_struct
\see ::_XLT_COUNTER_DATA
*/
typedef struct _XLT_COUNTER_DATA XLT_COUNTER_DATA;

/** \typedef XLT_TIMER_CMD
\ingroup xlt_tc_struct
Contains the command for setting the timer.
*/
typedef XLT_TIMER_DATA XLT_TIMER_CMD;

/** \typedef XLT_COUNTER_CMD
\ingroup xlt_tc_struct
Contains the command for setting a counter. It has the same structure of ::_XLT_COUNTER_DATA
\see ::_XLT_COUNTER_DATA
*/
typedef XLT_COUNTER_DATA XLT_COUNTER_CMD;

/** \union _XLT_TC_INFO
\ingroup xlt_tc_struct
Union of all timer and counters command and  data, that is:
::XLT_TIMER_DATA, ::XLT_TIMER_ADD_CMD, ::XLT_COUNTER_DATA, ::XLT_TIMER_CMD and ::XLT_COUNTER_CMD.
*/
union _XLT_TC_INFO{
	XLT_COUNTER_DATA counter_data[XLT_COUNTERS_NUM]; ///< array of XLT_COUNTER_DATA type containing information of all the counters.
	XLT_TIMER_DATA timer_data;	///< XLT_TIMER_DATA type: counter information.
	XLT_COUNTER_CMD counter_cmd; ///<XLT_COUNTER_CMD type: counter command.
	XLT_TIMER_CMD timer_cmd; ///< XLT_TIMER_CMD type: timer command.
	XLT_TIMER_ADD_CMD timer_add_value_cmd; ///< XLT_TIMER_ADD_CMD type: add timer command
};

/** \typedef XLT_TC_INFO
\ingroup xlt_tc_struct
\see ::_XLT_TC_INFO
*/
typedef union _XLT_TC_INFO XLT_TC_INFO;


/** \defgroup XLT_TIMER_COUNTER_INFO XLT_TIMER_COUNTER_INFO structure
\ingroup xlt_tc
Contains the data retrieved by the function xlt_timer_counters_retrieve() and consist of timer or counter info retrieved from 
an XLight device or from an encrypted command to be sent to the device
 @{
 */

/** Timer and counters info retrieved from an XLight device
*/
typedef struct _XLT_TIMER_COUNTER_INFO{	
	unsigned int type;///< type of data contained int the 'tc' argument. It may takes the \ref XLT_TIMER_COUNTER_INFO_types values
	unsigned int rfu;///< Reserved for future usage
	XLT_TC_INFO tc;///< the data retrieved from the XLight device 
}XLT_TIMER_COUNTER_INFO;
//@} //XLT_TIMER_COUNTER_INFO

/** \defgroup XLT_TIMER_COUNTER_INFO_types XLT_TIMER_COUNTER_INFO data types
\ingroup xlt_tc_defines
These are the value types associated to the data contained int the structure XLT_TIMER_COUNTER_INFO.
@{
*/
#define XLT_TC_UNKNOWN 0 ///< Unknown data
#define XLT_TC_WRITE_COUNTER_CMD 1 ///< the data in the structure are related to a write counter command (xlt_generate_counter_settings())
#define XLT_TC_WRITE_TIMER_CMD 2 ///< the data in the structure are related to a write timer command (xlt_generate_timer_settings())
#define XLT_TC_ADD_TIMER_VALUE_CMD 3 ///< the data in the structure are related to a add timer command (xlt_generate_timer_add_settings())
#define XLT_TC_READ_COUNTERS_DATA 4 ///< the data in the structure are related to read counters info (xlt_enc_read_counters())
#define XLT_TC_READ_TIMER_DATA 5 ///< the data in the structure are related to read timer info (xlt_enc_read_timer())
//@} //XLT_TIMER_COUNTER_INFO_types


/** \defgroup xlt_tc_defines Timer and counter definitions
 \ingroup xlt_defines
 \ingroup xlt_tc
 @{
 */
#define XLT_GENERATE_COUNTER_SETTINGS_CMD_ENC_SIZE 60 ///< size of the encrypted buffer returned by xlt_generate_counter_settings()
#define XLT_GENERATE_TIMER_SETTINGS_CMD_ENC_SIZE 44 ///< size of the encrypted buffer returned by xlt_generate_timer_settings()
#define XLT_GENERATE_TIMER_ADD_SETTINGS_CMD_ENC_SIZE 44 ///< size of the encrypted buffer returned by xlt_generate_timer_add_settings()
#define XLT_ENC_READ_COUNTERS_DATA_SIZE 156 ///< size of the encrypted buffer returned by xlt_enc_read_counters()
#define XLT_ENC_READ_TIMER_DATA_SIZE 44 ///< size of the encrypted buffer returned by xlt_enc_read_timer()
//@}


/** \defgroup Lock_mask Lock mask values
 \ingroup xlt_defines
 \ingroup xlt_bank
 * Locking mask to instruct the XLight device which function must be locked on timer expiration on or counter reset (reach values '0').
 @{
 */
#define XLT_LOCK_READ_DATA_B0 (((XLT_ULONG_LONG)1) << 0) ///< Lock the function "Read from bank 0".
#define XLT_LOCK_READ_DATA_B1 (((XLT_ULONG_LONG)1) << 1) ///< Lock the function "Read from bank 1".
#define XLT_LOCK_READ_DATA_B2 (((XLT_ULONG_LONG)1) << 2) ///< Lock the function "Read from bank 2".
#define XLT_LOCK_READ_DATA_B3 (((XLT_ULONG_LONG)1) << 3) ///< Lock the function "Read from bank 3".
#define XLT_LOCK_READ_DATA_B4 (((XLT_ULONG_LONG)1) << 4) ///< Lock the function "Read from bank 4".
#define XLT_LOCK_READ_DATA_B5 (((XLT_ULONG_LONG)1) << 5) ///< Lock the function "Read from bank 5".
#define XLT_LOCK_READ_DATA_B6 (((XLT_ULONG_LONG)1) << 6) ///< Lock the function "Read from bank 6".
#define XLT_LOCK_RESERVED_7 (((XLT_ULONG_LONG)1) << 7) ///< RFU
#define XLT_LOCK_WRITE_DATA_B0 (((XLT_ULONG_LONG)1) << 8) ///< Lock the function "Write on bank 0".
#define XLT_LOCK_WRITE_DATA_B1 (((XLT_ULONG_LONG)1) << 9) ///< Lock the function "Write on bank 1".
#define XLT_LOCK_WRITE_DATA_B2 (((XLT_ULONG_LONG)1) << 10) ///< Lock the function "Write on bank 2".
#define XLT_LOCK_WRITE_DATA_B3 (((XLT_ULONG_LONG)1) << 11) ///< Lock the function "Write on bank 3".
#define XLT_LOCK_WRITE_DATA_B4 (((XLT_ULONG_LONG)1) << 12) ///< Lock the function "Write on bank 4".
#define XLT_LOCK_WRITE_DATA_B5 (((XLT_ULONG_LONG)1) << 13) ///< Lock the function "Write on bank 5".
#define XLT_LOCK_WRITE_DATA_B6 (((XLT_ULONG_LONG)1) << 14) ///< Lock the function "Write on bank 6".
#define XLT_LOCK_RESERVED_15 (((XLT_ULONG_LONG)1) << 15) ///< RFU
#define XLT_LOCK_SESSION_CRYPT_0 (((XLT_ULONG_LONG)1) << 16) ///< Lock the function "Session Encryption with key of index 0".
#define XLT_LOCK_SESSION_CRYPT_1 (((XLT_ULONG_LONG)1) << 17) ///< Lock the function "Session Encryption with key of index 1".
#define XLT_LOCK_SESSION_CRYPT_2 (((XLT_ULONG_LONG)1) << 18) ///< Lock the function "Session Encryption with key of index 2".
#define XLT_LOCK_SESSION_CRYPT_3 (((XLT_ULONG_LONG)1) << 19) ///< Lock the function "Session Encryption with key of index 3".
#define XLT_LOCK_SESSION_CRYPT_4 (((XLT_ULONG_LONG)1) << 20) ///< Lock the function "Session Encryption with key of index 4".
#define XLT_LOCK_SESSION_CRYPT_5 (((XLT_ULONG_LONG)1) << 21) ///< Lock the function "Session Encryption with key of index 5".
#define XLT_LOCK_SESSION_CRYPT_6 (((XLT_ULONG_LONG)1) << 22) ///< Lock the function "Session Encryption with key of index 6".
#define XLT_LOCK_SESSION_CRYPT_7 (((XLT_ULONG_LONG)1) << 23) ///< Lock the function "Session Encryption with key of index 7".
#define XLT_LOCK_SESSION_DECRYPT_0 (((XLT_ULONG_LONG)1) << 24) ///< Lock the function "Session Decryption with key of index 0".
#define XLT_LOCK_SESSION_DECRYPT_1 (((XLT_ULONG_LONG)1) << 25) ///< Lock the function "Session Decryption with key of index 1".
#define XLT_LOCK_SESSION_DECRYPT_2 (((XLT_ULONG_LONG)1) << 26) ///< Lock the function "Session Decryption with key of index 2".
#define XLT_LOCK_SESSION_DECRYPT_3 (((XLT_ULONG_LONG)1) << 27) ///< Lock the function "Session Decryption with key of index 3".
#define XLT_LOCK_SESSION_DECRYPT_4 (((XLT_ULONG_LONG)1) << 28) ///< Lock the function "Session Decryption with key of index 4".
#define XLT_LOCK_SESSION_DECRYPT_5 (((XLT_ULONG_LONG)1) << 29) ///< Lock the function "Session Decryption with key of index 5".
#define XLT_LOCK_SESSION_DECRYPT_6 (((XLT_ULONG_LONG)1) << 30) ///< Lock the function "Session Decryption with key of index 6".
#define XLT_LOCK_SESSION_DECRYPT_7 (((XLT_ULONG_LONG)1) << 31) ///< Lock the function "Session Decryption with key of index 7".
#define XLT_LOCK_RSA_CRT_SET_KEY_512 (((XLT_ULONG_LONG)1) << 32) ///< Lock the function "Set RSA 512 key".
#define XLT_LOCK_RSA_CRT_SET_KEY_1024 (((XLT_ULONG_LONG)1) << 33) ///< Lock the function "Set RSA 1024 key". 
#define XLT_LOCK_RSA_CRT_DECRYPT_512 (((XLT_ULONG_LONG)1) << 34) ///< Lock the function "Decrypt with RSA 512 key".
#define XLT_LOCK_RSA_CRT_DECRYPT_1024 (((XLT_ULONG_LONG)1) << 35) ///< Lock the function "Decrypt with RSA 1024 key".
#define XLT_LOCK_RESERVED_36 (((XLT_ULONG_LONG)1) << 36) ///< RFU
#define XLT_LOCK_RESERVED_37 (((XLT_ULONG_LONG)1) << 37) ///< RFU
#define XLT_LOCK_RESERVED_38 (((XLT_ULONG_LONG)1) << 38) ///< RFU
#define XLT_LOCK_RESERVED_39 (((XLT_ULONG_LONG)1) << 39) ///< RFU
#define XLT_LOCK_CRYPT_ECB (((XLT_ULONG_LONG)1) << 40) ///< Lock the function xlt_encrypt()
#define XLT_LOCK_DECRYPT_ECB (((XLT_ULONG_LONG)1) << 41) ///< Lock the function xlt_decrypt()
#define XLT_LOCK_CHALLENGE_ECB (((XLT_ULONG_LONG)1) << 42) ///< Lock the function xlt_challenge()
#define XLT_LOCK_RESERVED_43 (((XLT_ULONG_LONG)1) << 43) ///< RFU
#define XLT_LOCK_RESERVED_44 (((XLT_ULONG_LONG)1) << 44) ///< RFU
#define XLT_LOCK_RESERVED_45 (((XLT_ULONG_LONG)1) << 45) ///< RFU
#define XLT_LOCK_RESERVED_46 (((XLT_ULONG_LONG)1) << 46) ///< RFU
#define XLT_LOCK_RESERVED_47 (((XLT_ULONG_LONG)1) << 47) ///< RFU
//@} // Lock_mask

/** \defgroup Trigger_mask Trigger mask values
 \ingroup xlt_defines
 * Trigger mask to instruct the XLight device to decrement a counter when a specific function is called.
 @{
 */
#define XLT_TRIGGER_READ_DATA_B0 XLT_LOCK_READ_DATA_B0 ///< Decrement a given counter when it is called the function "Read from bank 0".
#define XLT_TRIGGER_READ_DATA_B1 XLT_LOCK_READ_DATA_B1 ///< Decrement a given counter when it is called the function "Read from bank 1".
#define XLT_TRIGGER_READ_DATA_B2 XLT_LOCK_READ_DATA_B2 ///< Decrement a given counter when it is called the function "Read from bank 2".
#define XLT_TRIGGER_READ_DATA_B3 XLT_LOCK_READ_DATA_B3 ///< Decrement a given counter when it is called the function "Read from bank 3".
#define XLT_TRIGGER_READ_DATA_B4 XLT_LOCK_READ_DATA_B4 ///< Decrement a given counter when it is called the function "Read from bank 4".
#define XLT_TRIGGER_READ_DATA_B5 XLT_LOCK_READ_DATA_B5 ///< Decrement a given counter when it is called the function "Read from bank 5".
#define XLT_TRIGGER_READ_DATA_B6 XLT_LOCK_READ_DATA_B6 ///< Decrement a given counter when it is called the function "Read from bank 6".
#define XLT_TRIGGER_RESERVED_7 XLT_LOCK_RESERVED_7 ///< RFU
#define XLT_TRIGGER_WRITE_DATA_B0 XLT_LOCK_WRITE_DATA_B0 ///< Decrement a given counter when it is called the function "Write on bank 0".
#define XLT_TRIGGER_WRITE_DATA_B1 XLT_LOCK_WRITE_DATA_B1 ///< Decrement a given counter when it is called the function "Write on bank 1".
#define XLT_TRIGGER_WRITE_DATA_B2 XLT_LOCK_WRITE_DATA_B2 ///< Decrement a given counter when it is called the function "Write on bank 2".
#define XLT_TRIGGER_WRITE_DATA_B3 XLT_LOCK_WRITE_DATA_B3 ///< Decrement a given counter when it is called the function "Write on bank 3".
#define XLT_TRIGGER_WRITE_DATA_B4 XLT_LOCK_WRITE_DATA_B4 ///< Decrement a given counter when it is called the function "Write on bank 4".
#define XLT_TRIGGER_WRITE_DATA_B5 XLT_LOCK_WRITE_DATA_B5 ///< Decrement a given counter when it is called the function "Write on bank 5".
#define XLT_TRIGGER_WRITE_DATA_B6 XLT_LOCK_WRITE_DATA_B6 ///< Decrement a given counter when it is called the function "Write on bank 6".
#define XLT_TRIGGER_RESERVED_15 XLT_LOCK_RESERVED_15 ///< RFU
#define XLT_TRIGGER_SESSION_CRYPT_0 XLT_LOCK_SESSION_CRYPT_0 ///< Decrement a given counter when it is called the function "Session Encryption with key of index 0".
#define XLT_TRIGGER_SESSION_CRYPT_1 XLT_LOCK_SESSION_CRYPT_1 ///< Decrement a given counter when it is called the function "Session Encryption with key of index 1".
#define XLT_TRIGGER_SESSION_CRYPT_2 XLT_LOCK_SESSION_CRYPT_2 ///< Decrement a given counter when it is called the function "Session Encryption with key of index 2".
#define XLT_TRIGGER_SESSION_CRYPT_3 XLT_LOCK_SESSION_CRYPT_3 ///< Decrement a given counter when it is called the function "Session Encryption with key of index 3".
#define XLT_TRIGGER_SESSION_CRYPT_4 XLT_LOCK_SESSION_CRYPT_4 ///< Decrement a given counter when it is called the function "Session Encryption with key of index 4".
#define XLT_TRIGGER_SESSION_CRYPT_5 XLT_LOCK_SESSION_CRYPT_5 ///< Decrement a given counter when it is called the function "Session Encryption with key of index 5".
#define XLT_TRIGGER_SESSION_CRYPT_6 XLT_LOCK_SESSION_CRYPT_6 ///< Decrement a given counter when it is called the function "Session Encryption with key of index 6".
#define XLT_TRIGGER_SESSION_CRYPT_7 XLT_LOCK_SESSION_CRYPT_7 ///< Decrement a given counter when it is called the function "Session Encryption with key of index 7".
#define XLT_TRIGGER_SESSION_DECRYPT_0 XLT_LOCK_SESSION_DECRYPT_0 ///< Decrement a given counter when it is called the function "Session Decryption with key of index 0".
#define XLT_TRIGGER_SESSION_DECRYPT_1 XLT_LOCK_SESSION_DECRYPT_1 ///< Decrement a given counter when it is called the function "Session Decryption with key of index 1".
#define XLT_TRIGGER_SESSION_DECRYPT_2 XLT_LOCK_SESSION_DECRYPT_2 ///< Decrement a given counter when it is called the function "Session Decryption with key of index 2".
#define XLT_TRIGGER_SESSION_DECRYPT_3 XLT_LOCK_SESSION_DECRYPT_3 ///< Decrement a given counter when it is called the function "Session Decryption with key of index 3".
#define XLT_TRIGGER_SESSION_DECRYPT_4 XLT_LOCK_SESSION_DECRYPT_4 ///< Decrement a given counter when it is called the function "Session Decryption with key of index 4".
#define XLT_TRIGGER_SESSION_DECRYPT_5 XLT_LOCK_SESSION_DECRYPT_5 ///< Decrement a given counter when it is called the function "Session Decryption with key of index 5".
#define XLT_TRIGGER_SESSION_DECRYPT_6 XLT_LOCK_SESSION_DECRYPT_6 ///< Decrement a given counter when it is called the function "Session Decryption with key of index 6".
#define XLT_TRIGGER_SESSION_DECRYPT_7 XLT_LOCK_SESSION_DECRYPT_7 ///< Decrement a given counter when it is called the function "Session Decryption with key of index 7".
#define XLT_TRIGGER_RSA_CRT_SET_KEY_512 XLT_LOCK_RSA_CRT_SET_KEY_512 ///< Decrement a given counter when it is called the function "Set RSA 512 key".
#define XLT_TRIGGER_RSA_CRT_SET_KEY_1024 XLT_LOCK_RSA_CRT_SET_KEY_1024 ///< Decrement a given counter when it is called the function "Set RSA 1024 key".
#define XLT_TRIGGER_RSA_CRT_DECRYPT_512 XLT_LOCK_RSA_CRT_DECRYPT_512 ///< Decrement a given counter when it is called the function "Decrypt with RSA 512 key".
#define XLT_TRIGGER_RSA_CRT_DECRYPT_1024 XLT_LOCK_RSA_CRT_DECRYPT_1024 ///< Decrement a given counter when it is called the function "Decrypt with RSA 1024 key".
#define XLT_TRIGGER_RESERVED_36 XLT_LOCK_RESERVED_36 ///< RFU
#define XLT_TRIGGER_RESERVED_37 XLT_LOCK_RESERVED_37 ///< RFU
#define XLT_TRIGGER_RESERVED_38 XLT_LOCK_RESERVED_38 ///< RFU
#define XLT_TRIGGER_RESERVED_39 XLT_LOCK_RESERVED_39 ///< RFU
#define XLT_TRIGGER_CRYPT_ECB XLT_LOCK_CRYPT_ECB ///< Decrement a given counter when it is called the function xlt_encrypt().
#define XLT_TRIGGER_DECRYPT_ECB XLT_LOCK_DECRYPT_ECB ///< Decrement a given counter when it is called the function xlt_decrypt().
#define XLT_TRIGGER_CHALLENGE_ECB XLT_LOCK_CHALLENGE_ECB ///< Decrement a given counter when it is called the function xlt_challenge().
#define XLT_TRIGGER_RESERVED_43 XLT_LOCK_RESERVED_43 ///< RFU
#define XLT_TRIGGER_RESERVED_44 XLT_LOCK_RESERVED_44 ///< RFU
#define XLT_TRIGGER_RESERVED_45 XLT_LOCK_RESERVED_45 ///< RFU
#define XLT_TRIGGER_RESERVED_46 XLT_LOCK_RESERVED_46 ///< RFU
#define XLT_TRIGGER_RESERVED_47 XLT_LOCK_RESERVED_47 ///< RFU
#define XLT_TRIGGER_GET_INFO (((XLT_ULONG_LONG)1) << 48) ///< Decrement a given counter when it is called the function xlt_getinfo() or xlt_locate().
#define XLT_TRIGGER_AES_TRAP (((XLT_ULONG_LONG)1) << 49) ///< Decrement a given counter  when it is called aes session encryption decryption on "trap keys"
//LOCK_RESERVED_49_63
//@} // Trigger_mask

/**
Define for locking all the lockable functions.
*/
#define XLT_LOCK_ALL (\
XLT_LOCK_READ_DATA_B0 | XLT_LOCK_READ_DATA_B1 | XLT_LOCK_READ_DATA_B2 | XLT_LOCK_READ_DATA_B3 | XLT_LOCK_READ_DATA_B4 |\
XLT_LOCK_READ_DATA_B5 | XLT_LOCK_READ_DATA_B6 | XLT_LOCK_WRITE_DATA_B0 | XLT_LOCK_WRITE_DATA_B1 | XLT_LOCK_WRITE_DATA_B2 |\
XLT_LOCK_WRITE_DATA_B3 | XLT_LOCK_WRITE_DATA_B4 | XLT_LOCK_WRITE_DATA_B5 | XLT_LOCK_WRITE_DATA_B6 | XLT_LOCK_SESSION_CRYPT_0 |\
XLT_LOCK_SESSION_CRYPT_1 | XLT_LOCK_SESSION_CRYPT_2 | XLT_LOCK_SESSION_CRYPT_3 | XLT_LOCK_SESSION_CRYPT_4 | XLT_LOCK_SESSION_CRYPT_5 |\
XLT_LOCK_SESSION_CRYPT_6 | XLT_LOCK_SESSION_CRYPT_7 | XLT_LOCK_SESSION_DECRYPT_0 | XLT_LOCK_SESSION_DECRYPT_1 | XLT_LOCK_SESSION_DECRYPT_2 |\
XLT_LOCK_SESSION_DECRYPT_3 | XLT_LOCK_SESSION_DECRYPT_4 | XLT_LOCK_SESSION_DECRYPT_5 | XLT_LOCK_SESSION_DECRYPT_6 | XLT_LOCK_SESSION_DECRYPT_7 |\
XLT_LOCK_RSA_CRT_SET_KEY_512 | XLT_LOCK_RSA_CRT_SET_KEY_1024 | XLT_LOCK_RSA_CRT_DECRYPT_512 | XLT_LOCK_RSA_CRT_DECRYPT_1024 |\
XLT_LOCK_CRYPT_ECB | XLT_LOCK_DECRYPT_ECB | XLT_LOCK_CHALLENGE_ECB)

/**
Define for triggering all the triggerable functions.
*/
#define XLT_TRIGGER_ALL (XLT_LOCK_ALL | XLT_TRIGGER_GET_INFO)



// ===============================================================================

//\cond NOT_COMMENTED
#define DATE_STRUCT_DEFINED
//\endcond 

/** \struct _XLT_DATE_DATA
\ingroup date_str
Date license management data.
The structure contains the data of the XLight date management.
*/
struct _XLT_DATE_DATA{
	XLT_ULONG_LONG functions_to_lock_mask;///< bits mask of the functions that won't work after license expiration date (time update errors may lock the masked functions too). This mask is built making a birwise or of the values from \ref Lock_mask.
	unsigned int expiration_time;///< date of expiration time expressed int Unix Time (defined as the number of seconds that have elapsed since 00:00:00 Coordinated Universal Time (UTC), 1 January 1970).
	unsigned int device_time;///< the time retrieved by the XLight device. This time is expressed with a precision of five minutes and in Unix Time.
	unsigned int max_time_between_updates;///< the maximum time in seconds that is allowed to elapse between two successive date update onto the XLight device (when the device is not powered the time count is suspended)	.
	unsigned int max_time_between_signed_updates;///< the maximum time in seconds that is allowed to elapse between two successive 'signed date' update onto the XLight device
	unsigned int next_signed_update_time; ///< the date expressed in Unix Time within which the 'signed time' update must be done to avoid errors.
	unsigned int challenge_expiration_time;///< maximum allowed time duration expressed in seconds of the challenge-response procedure used for the 'signed time' update on XLight.
	unsigned int max_update_date_error;///< the maximum number of errors that it is allowed to occur updating the XLight device date (usually caused by passing non acceptable time values). Whenever the number of errors pass this value all the functions specified by the locking mask will fail.
	unsigned int update_date_error; ///< current number of time update errors occurred (usually caused by passing non acceptable time values). Whenever the number of errors pass this value all the functions specified by the locking mask will fail.
	unsigned int max_missing_update_date_error;///< the maximum number of time that it is accepted a missing (non signed) date update within the expected time. Whenever the number of errors pass this value all the functions specified by the locking mask will fail.
	unsigned int missing_update_date_error;///< current number of "max_missing_update_date_error" type errors occurred.
	unsigned int max_missing_update_signed_date_error;///< the maximum number of time that it is accepted a missing 'signed date' update within the expected time.
	unsigned int missing_update_signed_date_error;///< current number of "max_missing_update_signed_date_error" type errors occurred.
	unsigned int stop_reason;///< if the functions are locked this value contains the status code for the reason that caused the lock.
	unsigned int cmd_counter;///< strictly increasing value used to avoid command reuse. This is the last value used for this field.
	unsigned int serial_number;///< the serial number of the referred XLight device
	unsigned int _unused;///< unused
};

/** \typedef XLT_DATE_DATA
\ingroup date_str
\see ::_XLT_DATE_DATA
*/
typedef struct _XLT_DATE_DATA XLT_DATE_DATA;

/** \defgroup xlt_date_def Definitions
\ingroup xlt_date
@{
*/

/** Date reason for device halting
This value is a mask of bits returned by stop_reason field in the structure XLT_DATE_DATA
*/
#define XLT_DATE_STOP_FOR_DATE_EXPIRATION 0x01 ///< the license time is expired.
#define XLT_DATE_STOP_FOR_UPDATE_MAX_ERROR 0x02 ///< the number of allowed error during time update was passed.
#define XLT_DATE_STOP_FOR_NORMAL_UPDATE_TIME_OUT_MAX_ERROR 0x04 ///< the number of missing time update was passed (too long time without date update).
#define XLT_DATE_STOP_FOR_SIGNED_UPDATE_TIME_OUT_MAX_ERROR 0x08 ///< the number of missing signed time update was passed (too long time without signed date update).
#define XLT_DATE_CHALLENGE_SIZE 16 ///< the size of the challenge buffer for signed 
//@}

/** \struct _XLT_DATE_CHALLENGE
\ingroup date_str
Date license challenge for signed time update.
When running signed time update the XLight device returns the following values to manage the update process
*/
struct _XLT_DATE_CHALLENGE{
	unsigned int serial_number; ///< the serial number of the referred XLight device.
	unsigned int reserved;///< reserved value managed by XLight functions.
	unsigned char challenge[XLT_DATE_CHALLENGE_SIZE]; ///< challenge data.
};

/** \typedef XLT_DATE_CHALLENGE
\ingroup date_str
\see ::_XLT_DATE_CHALLENGE
*/
typedef struct _XLT_DATE_CHALLENGE XLT_DATE_CHALLENGE;

//\ingroup xlt_date_def
#define CHALLENGE_EXPIRATION_MAX_TIME (3600 * 24 * 7)///< the maximimum time in seconds that challenge_expiration_time can assume (seven days)

/** \struct _XLT_DATE_SET_EXPIRATION_CMD
\ingroup date_str
Set expiration date command.
Values that must be set to initialize an XLight device for managing the license based on date expiration.
*/
struct _XLT_DATE_SET_EXPIRATION_CMD{
	XLT_ULONG_LONG functions_to_lock_mask;///< bits mask of the functions that won't work after license expiration date (time update errors may lock the masked functions too). This mask is built making a birwise or of the values from \ref Lock_mask.
	unsigned int expiration_time;///< date of expiration time expressed int Unix Time (defined as the number of seconds that have elapsed since 00:00:00 Coordinated Universal Time (UTC), 1 January 1970).
	unsigned int current_time;///< the current time. This time is expressed in Unix Time.
	unsigned int max_time_between_updates;///< the maximum time in seconds that is allowed to elapse between two successive normal date (i.e. not certified) update (when the device is not powered the time count is suspended).
	unsigned int max_time_between_signed_updates;///< the maximum time in seconds that is allowed to elapse between two successive certificated date update (when the device is not powered the time count is suspended).
	unsigned int challenge_expiration_time;///< maximum allowed time duration expressed in seconds of the challenge-response procedure used for the 'signed time' update on XLight.
	unsigned int max_update_date_error;///< the maximum number of errors that it is allowed to occur updating the XLight device date (usually caused by passing non acceptable time values). Whenever the number of errors pass this value the all the functions specified by the locking mask will fail
	unsigned int max_missing_update_date_error;///< the maximum number of time that the XLight device tolerates a missing time update. If this value is '0' no missing update is be accepted. Whenever the number of errors pass this value all the functions specified by the locking mask will fail.
	unsigned int max_missing_update_signed_date_error;///< the maximum number of time that the XLight device tolerates a missing 'signed time' update. If this value is '0' no missing update is be accepted. Whenever the number of errors pass this value all the functions specified by the locking mask will fail.
	unsigned int cmd_counter;///< strictly increasing value used to avoid command reuse.
	unsigned int serial_number;///< the serial number of the referred XLight device.
};

/** \typedef XLT_DATE_SET_EXPIRATION_CMD
\ingroup date_str
\see ::_XLT_DATE_SET_EXPIRATION_CMD
*/
typedef struct _XLT_DATE_SET_EXPIRATION_CMD XLT_DATE_SET_EXPIRATION_CMD;

/** \struct _XLT_DATE_SIGNED_DATE_CMD
\ingroup date_str
Signed date command structure
*/
struct _XLT_DATE_SIGNED_DATE_CMD{
	unsigned char challenge[XLT_DATE_CHALLENGE_SIZE];///< the challenge buffer retrieved from the XLight device.
	unsigned int time;///< the current time. This time is expressed in Unix Time.
};

/** \typedef XLT_DATE_SIGNED_DATE_CMD
\ingroup date_str
\see ::_XLT_DATE_SIGNED_DATE_CMD
*/
typedef struct _XLT_DATE_SIGNED_DATE_CMD XLT_DATE_SIGNED_DATE_CMD;

/** \union _XLT_D_INFO
\ingroup date_str
Union of all date command and  data, that is:
::XLT_DATE_SET_EXPIRATION_CMD, ::XLT_DATE_SIGNED_DATE_CMD, ::XLT_DATE_DATA, and ::XLT_DATE_CHALLENGE.
*/
union _XLT_D_INFO{
	XLT_DATE_SET_EXPIRATION_CMD date_exp_cmd; ///< XLT_DATE_SET_EXPIRATION_CMD type: set expiration command.
	XLT_DATE_SIGNED_DATE_CMD date_sig_cmd; ///< XLT_DATE_SIGNED_DATE_CMD type: signed date update command.
	XLT_DATE_DATA date_data; ///< XLT_DATE_DATA type: date information data.
	XLT_DATE_CHALLENGE date_challenge; ///<XLT_DATE_CHALLENGE type: challenge generated by the XLight device for signed date update procedure.
};

/** \typedef XLT_D_INFO
\ingroup date_str
\see ::_XLT_D_INFO
*/
typedef union _XLT_D_INFO XLT_D_INFO;


/** \defgroup XLT_DATE_INFO XLT_DATE_INFO structure
\ingroup xlt_date
Contains the data retrieved by the function xlt_date_enc_retrieve() and consist of date info retrieved from 
an XLight device or from an encrypted command to be sent to the device
@{
*/
/** \defgroup XLT_DATE_INFO_types XLT_DATE_INFO data types
These are the value types associated to the data contained int the structure XLT_TIMER_COUNTER_INFO.
@{
*/
#define XLT_DATE_TYPE_UNKNOWN 0 ///< Unknown data.
#define XLT_DATE_TYPE_SET_EXPIRATION_CMD 1 ///< set date expiration command.
#define XLT_DATE_TYPE_SIGNED_DATE_CMD 2 ///< set signed date command.
#define XLT_DATE_TYPE_DATA 3 ///< data containing information and settings of a date expiration management.
#define XLT_DATE_TYPE_CHALLENGE 4 ///< challenge data from XLight device needed to issue a set signed date command.
//@}
/** Date info retrieved from an XLight device
*/
typedef struct _XLT_DATE_INFO{
	unsigned int type;///< type of data contained int the 'tc' argument. It may takes the \ref XLT_TIMER_COUNTER_INFO_types values
	unsigned int rfu;///< Reserved for future usage
	XLT_D_INFO d;///< the data retrieved from the XLight device 
}XLT_DATE_INFO;
//@}

#define XLT_DATE_ENC_EXP_CMD_SIZE 76 ///< the length of the encrypted buffer containing the command for setting the expiration date
#define XLT_DATE_SIG_UPD_CMD_SIZE 44 ///< the length of the encrypted buffer containing the command for updating the signed date
#define XLT_DATE_ENC_CHALLENGE_SIZE 44 ///< the length of the get challenge encrypted buffer
#define XLT_DATE_READ_ENC_DATA_SIZE 76 ///< the length of the encrypted buffer containing encrypted date info

///
/** \defgroup xlt_date_manage_cmd Date management commands
\ingroup xlt_defines
\ingroup xlt_date
Date management commands of the xlt_date_manage() function.
@{
*/
#define XLT_DATE_MANAGE_AUTO_START 1 ///< start the automatic date management.
#define XLT_DATE_MANAGE_AUTO_STOP 2 ///< terminate the automatic date management.
#define XLT_DATE_MANAGE_DO_SET_TIME 3 ///< immdiately run date update onto the attached devices.
#define XLT_DATE_MANAGE_DO_SET_TIME_ASYNC 4 ///< immdiately start the date update onto the attached devices but not wait for completion.
#define XLT_DATE_MANAGE_DO_SET_TIME_RESULT 5 ///< get the status result of the execution xlt_date_manage() called with command argument ::XLT_DATE_MANAGE_DO_SET_TIME_ASYNC.
#define XLT_DATE_MANAGE_CLEAN_STATE 6 ///< cleanup the thread management status (that is the value retrieved using ::XLT_DATE_MANAGE_DO_SET_TIME_RESULT).
#define XLT_DATE_MANAGE_SET_IDLE_TIME_SEC 7 ///< set the idle timeout for the thread management (better not to choose less than 60 seconds and no more the half of the time refresh neeeded for the device time). Don't change this value if not needed.
#define XLT_DATE_MANAGE_MAKE_LOGS 8 ///< start or stop the log of the date management thread.
#define XLT_DATE_MANAGE_CLEAN_LOG 9 ///< cleanup logs.
#define XLT_DATE_MANAGE_LOG_ONLY_ERROR 10 ///< set or reset the log trace only for failed operation.
#define XLT_DATE_MANAGE_LOG_SET_QUEUE_LEN 11 ///< set the maximum number of the log records kept in memory (max 10000 records).
//@}

/** \defgroup DATE_OPT_VAL Options update values
\ingroup xlt_defines
\ingroup xlt_date
These are the options values of the xlt_date_manage() function when called with the following command arguments:
<ul>
<li>::XLT_DATE_MANAGE_AUTO_START
<li>::XLT_DATE_MANAGE_DO_SET_TIME
<li>::XLT_DATE_MANAGE_DO_SET_TIME_ASYNC
</ul>
These values can be used together as bitmask.
@{
*/
#define XLT_DATE_OPT_USE_LOCAL_TIME 0x1 ///< the automatic date management thread (when needed) updates the date of the device using the time of the computer .
#define XLT_DATE_OPT_USE_INTERNET_TIME 0x2 ///< the automatic date management thread (when needed) updates the date of the device using internet time (NTP: Network Time Protocol).
#define XLT_DATE_OPT_USE_INTERNET_SIGNED_TIME 0x4 ///< the automatic date management thread (when needed) updates the signed date using the OxySec service.
#define XLT_DATE_OPT_IMMEDIATELY_USE_LOCAL_TIME 0x40 ///< the automatic date management thread immediately update the date of the device just after being started (also if not strictly necessary).
#define XLT_DATE_OPT_IMMEDIATELY_USE_INTERNET_TIME 0x80 ///< the automatic date management thread immediately update the date of the device just after being started using NTP (also if not strictly necessary).
#define XLT_DATE_OPT_IMMEDIATELY_USE_INTERNET_SIGNED_TIME 0x100 ///< the automatic date management thread immediately update the signed date of the device just after being started (also if not strictly necessary).
#define XLT_DATE_OPT_USE_INTERNET_TIME_FOR_SCHEDULING_TASKS 0x200 ///< this setting doesn't allow to use local time for library scheduling (the local time wont' be used at all).
//@}


//oxyservice = script.google.com/macros/s/AKfycbwKjS-n-Q3zuuu_37BjrUg7dnV1E2ZfBy0I5TsrnVLcZ5x8Rl4/exec
//ntp = pool.ntp.org
//oxyservice = script.google.com/macros/s/AKfycbwKjS-n-Q3zuuu_37BjrUg7dnV1E2ZfBy0I5TsrnVLcZ5x8Rl4/exec ;  ntp = pool.ntp.org

/** \defgroup LOG_INFO Log information
\ingroup xlt_date
The function xlt_date_manage_get_log_records() returns log info related to the activity of the automatic thread management (\see xlt_date_manage()).
@{
*/
//Log actions values
/** \defgroup LOG_ACTION_VALS Log action values
The entry action of the structure ::XLT_DATE_LOG assumes the following values describing in which context
an event or an error occurred
*/
#define LOG_ACTION_GET_DATE_INFO 1 ///< event or error while getting date info from the device
#define LOG_ACTION_SIGNED_TIME 2 ///< event or error while attempting to perform the signed date update procedure
#define LOG_ACTION_NTP_TIME 3 ///< event or error while getting the internet time
#define LOG_ACTION_LOCAL_TIME 4 ///< event or error while setting the date to the device using local time

/** Log structure
\ingroup LOG_INFO
This is the structure containing the log info produced by the automatic date management.
The function xlt_date_manage_get_log_records() returns an array of this structure.
*/
typedef struct _XLT_DATE_LOG{
	unsigned int time;///< Unix Time at which the log event occurred
	int action; ///< action performed while the error or event occurred
	int status; ///< status of the operation (error code \ref xlt_Errors)
	unsigned int device_index; ///< the index of the device on which the operation was done
	unsigned int log_counter; ///< numeric value assigned to the log entry (every record of the log has a unique increasing value)
}XLT_DATE_LOG;
//@}


/** \defgroup releases_feature Release Features
 \ingroup xlt_defines
 \ingroup xlt_device
 * List of the minimum supporting version for each new feature introduced by the XLight releases.
 @{
 */
#define LOCK2_AVAILABLE_MIN_VERSION_ON_MODEL_BASIC_USBHID 0x101 ///< minimum XLight version that supports the <i>Lock2</i> feature on basic XLight devices.
#define RSA_AVAILABLE_MIN_VERSION_ON_MODEL_BASIC_USBHID 0x200 ///< minimum XLight version that supports the RSA feature on basic XLight devices.
#define SESSION_KEY_AVAILABLE_MIN_VERSION_ON_MODEL_BASIC_USBHID 0x200 ///< minimum XLight version that supports the <i>AES Session Key</i> feature on basic XLight devices.
#define SD_MEM_AVAILABLE_MIN_VERSION_ON_MODEL_BASIC_USBHID 0xffff ///< minimum XLight version that supports the <i>SD memory</i> feature on basic XLight devices (no basic XLight device supports this feature).
#define TIMER_AVAILABLE_MIN_VERSION_ON_MODEL_BASIC_USBHID 0x210 ///< minimum XLight version that supports timer and counter management on basic XLight devices.
#define DATE_AVAILABLE_MIN_VERSION_ON_MODEL_BASIC_USBHID 0x220 ///< minimum XLight version that supports timer and counter management on basic XLight devices.
#define SESSION_AVAILABLE_MIN_VERSION_ON_MODEL_BASIC_USBHID 0x230 ///< minimum XLight version that supports <i>session</i> management on basic XLight devices.
#define RSA_BOUND_TO_SN_MIN_VERSION_ON_MODEL_BASIC_USBHID 0x240 ///< minimum XLight version that supports <i>Rsa bound to serial</i> management on basic XLight devices.
#define TRAP_MIN_VERSION_ON_MODEL_BASIC_USBHID 0x240 ///< minimum XLight version that supports <i>trap</i> management on basic XLight devices.
#define MODULE_MANAGEMENT_ON_MODEL_BASIC_USBHID 0x250 ///< minimum XLight version that supports module management (see \ref xnd_modules, and \ref xnd_module_challenge) on basic XLight devices.

#define LOCK2_AVAILABLE_MIN_VERSION_ON_MODEL_USBHID_SD 0x100 ///< minimum XLight version that supports the <i>Lock2</i> feature on <i>XLight SD</i> devices.
#define RSA_AVAILABLE_MIN_VERSION_ON_MODEL_USBHID_SD 0x100 ///< minimum XLight version that supports the RSA feature on <i>XLight SD</i> devices.
#define SESSION_KEY_AVAILABLE_MIN_VERSION_ON_MODEL_USBHID_SD 0x100 ///< minimum XLight version that supports the <i>AES Session Key</i> feature on <i>XLight SD</i> devices.
#define SD_MEM_AVAILABLE_MIN_VERSION_ON_MODEL_USBHID_SD 0x100 ///< minimum XLight version that supports the <i>SD memory</i> feature on <i>XLight SD</i> devices.
#define TIMER_AVAILABLE_MIN_VERSION_ON_MODEL_USBHID_SD 0xffff ///< minimum XLight version that supports timer and counter management on <i>XLight SD</i> devices.
#define DATE_AVAILABLE_MIN_VERSION_ON_MODEL_USBHID_SD 0xffff ///< minimum XLight version that supports timer and counter management on <i>XLight SD</i> devices.
#define SESSION_AVAILABLE_MIN_VERSION_ON_MODEL_USBHID_SD 0x105 ///< minimum XLight version that supports <i>session</i> management on <i>XLight SD</i> devices.
#define RSA_BOUND_TO_SN_MIN_VERSION_ON_MODEL_USBHID_SD 0xffff ///< minimum XLight version that supports <i>Rsa bound to serial</i> management on <i>XLight SD</i> devices.
#define TRAP_MIN_VERSION_ON_MODEL_USBHID_SD 0xffff ///< minimum XLight version that supports <i>trap</i> management on <i>XLight SD</i> devices.
#define MODULE_MANAGEMENT_ON_MODEL_USBHID_SD 0xffff ///< minimum XLight version that supports module management (see \ref xnd_modules, and \ref xnd_module_challenge) on <i>XLight SD</i> devices.

//@} //releases_feature


/**
 * \ingroup xlt_device
 * Find a device with the specified label.
 * \param[in] label buffer of length ::XLT_LABEL_SIZE. Note that the comparison uses the whole size of the label, so the Label must not be 
 * considered as a string but as an array of characters of length ::XLT_LABEL_SIZE.
 * \return returns a value less than 0 if the label is not found, otherwise its index is returned. This index number must be used by any other function to access the device.
 * This index is passed as the argument named device.
 * \remark xlt_locate() is useful for easy access to a device, but if more than one device sharing the same label are plugged into the computer it's impossible 
 * to use this function for accessing all devices. Consider using a different way as shown in the example of xlt_getinfo(), where all the plugged devices are enumerated.

	\par Example
	\code
	int device;
	unsigned char label[XLT_LABEL_SIZE];

	strcpy((char*)label, "My XLight label");
	memset(label + strlen("My XLight label"), 0x00, sizeof(label) - strlen("My XLight label"));

	device = xlt_locate(label);
	if (device >= 0)
		printf("XLight device found at index %d\n", device);
	else
		printf("XLight device NOT found\n");
	...
	\endcode
 
 */
XLT_LINK int XLT_API xlt_locate(const unsigned char* label);



/**
 * \ingroup xlt_device
 * Return information about the selected device.
 * \param[in] device device index for the selection of a specific XLight device. This value runs from 0 to ::XLT_DEVICE_EXT_MAX -1.
 * \param[out] pversion points to an unsigned int where the version number of the device must be returned. If <i>pversion</i> is NULL this parameter is ignored.
 * \param[out] pmodel points to an unsigned int where the device model identification code must be returned. If <i>pmodel</i> is NULL this parameter is ignored.
 * \param[out] pflags points to an unsigned int where the \ref Flags of the device must be returned. If <i>pflags</i> is NULL this parameter is ignored.
 * \param[out] pserial points to an unsigned int where the serial number of the device must be returned. If <i>pserial</i> is NULL this parameter is ignored.
 * \param[out] label points to the memory location where the label of the device must be returned. If <i>label</i> is NULL this parameter is ignored.
 \return returns ::XLT_ERROR_SUCCESS on success, an \ref xlt_Errors "error code" on failure.
 \remark each device is associated to a unique device number and must be used by every function (except xlt_locate()) to address the device.
 The user must not rely on this number to infer the order of insertion or the physical position of an XLight device in the USB HUB of the host computer.
 * \par Example
 * \code
	#include "xlt.h"
	#include <stdio.h>
	#include <string.h>

    ...
	int status;
	unsigned int version;
	unsigned int model;
	unsigned int flags;
	unsigned int serial;
	unsigned char label_printable[XLT_LABEL_SIZE + 1];
	int i;
	unsigned int device;

	for(device = 0; device < XLT_DEVICE_EXT_MAX; device++){
		status = xlt_getinfo(device, &version, &model, &flags, &serial, label_printable);
		if (status == XLT_ERROR_NOT_FOUND)
			printf("Device not found at index %d!\n", device);
		else if (status != XLT_ERROR_SUCCESS)
			printf("An error has occurred!\n");
		else {
			printf("An XLight device was found plugged into the logical port %d\n", device);
			printf("Version: %x.%02x\n", version >> 8, version & 0xFF);
			if (model != XLT_MODEL_BASIC_USBHID)
				printf("Unrecognized model!\n");
			if (flags & XLT_FLAG_SETUP){
				printf("The device is initialized\n");
				for(i = 0; i < XLT_NUMBER_OF_BANKS; i++){
					if (flags & (XLT_FLAG_FROZEN_BANK0 << i))
						printf("Bank %d frozen\n", i);
				}
			}
			else
				printf("The device is NOT initialized\n");

			printf("The device Serial Number is: 0x%x\n", serial);
			label_printable[XLT_LABEL_SIZE] = 0;
			//N.B.: a label may contain not printable character
			printf("Label: %s\n", (char*) label_printable);
		}
	}
	...
 * \endcode
 */
XLT_LINK int XLT_API xlt_getinfo(unsigned int device, unsigned int* pversion, unsigned int* pmodel, unsigned int* pflags, unsigned int* pserial, unsigned char* label);


/**
 * \ingroup xlt_adv
 Set the label, the password and the cryptographic keys of the device.
 <p>
 <strong>Warning! This function can be executed only once!</strong> All the subsequent calls will fail.
 \note <b> this function produces an irreversible setting onto the XLight device, hence use it very carefully.</b>
 <p>

 \param[in] device device index for the selection of a specific XLight device. This value runs from 0 to ::XLT_DEVICE_EXT_MAX -1.
 \param[in] label points to a buffer of length ::XLT_LABEL_SIZE. It contains the label, that is the identification name to be assigned to the device.
 \param[in] password points to a buffer of length ::XLT_PASSWORD_SIZE. It contains the password to be assigned to the device.
 \param[in] dongle_key points to a buffer of length ::XLT_KEY_SIZE. It contains <i>Dongle Key</i>: the AES-256 key that will be used, for instance, by the functions xlt_encrypt() and xlt_decrypt().
 \param[in] cr_key points to a buffer of length ::XLT_KEY_SIZE. It contains an AES-256 key (<i>Challenge Key</i>) that will be used by the functions xlt_challenge().
 \return returns ::XLT_ERROR_SUCCESS on success, an \ref xlt_Errors "error code" on failure.
 \remark <i>password</i>, <i>dongle_key</i> (the <i>Dongle Key</i>) and <i>cr_key</i> (the <i>Challenge Response Key</i> or shortly <i>Challenge Key</i>) are optional arguments and they can be set to 0 (NULL).
 Whenever one of these entry is null it is considered as if it was an array of bytes filled with the value 0xFF (255 decimal). In other word, passing NULL is equivalent of passing a 0xFF bytes array.
 \note though <i>password</i>, <i>Dongle Key</i> and <i>Challenge Key</i> are optional, it is strongly recommended to set them with non trivial values
 to forbid memory access (using <i>password</i>) to unauthorized application, and to allow the protected application to make sure of the presence of the XLight device (using <i>Challenge Key</i>) 
 which constitutes the key point of the software protection.
 
 \note before calling xlt_setup() a device is in a non initialized state. In this context only the functions xlt_getinfo() and xlt_close() works.

 \note Never put <i>Dongle Key</i> inside the protected application. This is a key on which many security features are based on, inserting it inside the
 protected application may yield fundamental information to hackers for emulating the <i>XLight</i> device also in its more advanced feaures.
 \par Example
 \code
	#include "xlt.h"
	#include <stdio.h>

	...

 	int status;
	unsigned char label[XLT_LABEL_SIZE];
	unsigned char password[XLT_PASSWORD_SIZE];
	unsigned char dongle_key[XLT_KEY_SIZE];
	unsigned char challenge_response_key[XLT_KEY_SIZE];

	...

	//xlt_setup set label, password, user and challenge response keys (dongle_key and challenge_response_key) once for all.
	//Only label must be specified, but it is strongly recommeded to set password, dongle_key, challenge_response_key as well
	//with non trivial (random) values and keep them secret.
	
	//BEWARE: label, password, dongle_key and challenge_response_key are not strings but arrays,
	//so fill them up to their entire size

	strcpy((char*)label, "My XLight label");	
	memset(label + strlen("My XLight label"), 0x00, sizeof(label) - strlen("My XLight label"));	
	
	...

	status = xlt_setup(0, label, password, dongle_key, challenge_response_key);
	if (status != XLT_ERROR_SUCCESS){
		printf("An error has occurred");
	}
 * \endcode
 */
XLT_LINK int XLT_API xlt_setup(unsigned int device, const unsigned char* label, const unsigned char* password, const unsigned char* dongle_key, const unsigned char* cr_key);


/**
 * \ingroup xlt_bank
 Write into a memory bank of the XLight device.
 \param[in] device device index for the selection of a specific XLight device. This value runs from 0 to ::XLT_DEVICE_EXT_MAX -1.
 \param[in] password points to a buffer of length ::XLT_PASSWORD_SIZE that contains the password assigned to the device.
 \param[in] bank the index of the memory bank that must be written.
 \param[in] data points to a buffer of size ::XLT_BANK_SIZE containing the data to be written into the memory.
 \return returns ::XLT_ERROR_SUCCESS on success, an \ref xlt_Errors "error code" on failure.
 \remark the <i>password</i> entry must be the same that was used in xlt_setup() call. If it was NULL, it must be NULL also in xlt_write().

 \par Example
 \code
	...
	int status;
	unsigned int device = 0;
	unsigned char password[XLT_PASSWORD_SIZE];
	unsigned char data[XLT_BANK_SIZE];

	//BEWARE: data, is not a  not string but an array,
	//so fill it up to its entire size
	strcpy((char*)data, "Some data");
	memset(data + strlen("Some data"), 0x00, sizeof(data) - strlen("Some data"));	

	strcpy((char*)password, "My XLight password");
	memset(password + strlen("My XLight password"), 0x00, sizeof(password) - strlen("My XLight password"));	

	//write in bank 0 of an XLight dongle indexed by device = 0
	status = xlt_write(device, password, 0, data);
	if (status != XLT_ERROR_SUCCESS){
		printf("An error has occurred\n");
	}
	...
	\endcode
*/
XLT_LINK int XLT_API xlt_write(unsigned int device, const unsigned char* password, unsigned int bank, const unsigned char* data);


/**
 * \ingroup xlt_bank
 Read from a memory bank of the XLight device.
 \param[in] device device index for the selection of a specific XLight device. This value runs from 0 to ::XLT_DEVICE_EXT_MAX -1.
 \param[in] password points to a buffer of length ::XLT_PASSWORD_SIZE that contains the password assigned to the device.
 \param[in] bank the index of the memory bank that must be read.
 \param[out] data points to a buffer of size ::XLT_BANK_SIZE that will receive the data read from the adressed memory bank.
 \return returns ::XLT_ERROR_SUCCESS on success, an \ref xlt_Errors "error code" on failure.
 \remark the <i>password</i> entry must be the same that was used in xlt_setup() call. If it was NULL, it must be NULL also in xlt_read().

 \par Example
 \code
	...
	int status;
	unsigned int device = 0;
	unsigned char password[XLT_PASSWORD_SIZE];
	unsigned char data[XLT_BANK_SIZE];

	strcpy((char*)password, "My XLight password");
	memset(password + strlen("My XLight password"), 0x00, sizeof(password) - strlen("My XLight password"));	

	//read from bank 0 of an XLight dongle
	status = xlt_read(device, password, 0, data);
	if (status != XLT_ERROR_SUCCESS){
		printf("An error has occurred\n");
	}
	else {
		//N.B.: the data banks may contain not printable character 
		//(and in general it makes no sense print out memory content, this is just an example)
		printf("Bank 0 data: %s\n", (char*)data);
	}
	...
	\endcode
*/
XLT_LINK int XLT_API xlt_read(unsigned int device, const unsigned char* password, unsigned int bank, unsigned char* data);


/**
 * \ingroup xlt_bank
Freeze a given memory bank. After freezing it won't be possible write inside the given bank any longer.

\note <b> this function produces an irreversible setting onto the XLight device, hence use it very carefully.</b>

 \param[in] device device index for the selection of a specific XLight device. This value runs from 0 to ::XLT_DEVICE_EXT_MAX -1.
 \param[in] password points to a buffer of length ::XLT_PASSWORD_SIZE that contains the password assigned to the device.
 \param[in] bank the index of the memory bank that must be frozen.
 \return returns ::XLT_ERROR_SUCCESS on success, an \ref xlt_Errors "error code" on failure.
 \remark the <i>password</i> entry must be the same that was used in xlt_setup() call. If it was NULL, it must be NULL also in xlt_bank_freeze().

	\par Example
	\code
	...
	int status;
	unsigned int device = 0;
	unsigned char password[XLT_PASSWORD_SIZE];

	strcpy((char*)password, "My XLight password");
	memset(password + strlen("My XLight password"), 0x00, sizeof(password) - strlen("My XLight password"));

	//freeze the bank 0 of an XLight dongle
	//BEWARE: after the freeze the memory content of the bank 0 can't be modified any longer
	status = xlt_bank_freeze(device, password, 0);
	if (status != XLT_ERROR_SUCCESS){
		printf("An error has occurred\n");
	}
	...
	\endcode

*/
XLT_LINK int XLT_API xlt_bank_freeze(unsigned int device, const unsigned char* password, unsigned int bank);


/**
\deprecated
Perform AES-256 encryption 
 \param[in] device device index for the selection of a specific XLight device. This value runs from 0 to ::XLT_DEVICE_EXT_MAX -1.
 \param[in] plaintext points to the buffer of length ::XLT_CIPHERTEXT_SIZE containing the plaintext to encrypt.
 \param[out] ciphertext points to the buffer of length ::XLT_CIPHERTEXT_SIZE receiving the encrypted result.
 \return returns ::XLT_ERROR_SUCCESS on success, an \ref xlt_Errors "error code" on failure.
 \note the encryption function uses as cryptographic key the <i>Dongle Key</i> entry set by xlt_setup().
 \note We strongly recommend never to put <i>Dongle Key</i> in the protected application. Use <i>Dongle Key</i> to encrypt data, but not
 for authentication process like discussed in xlt_challenge() documentation. 


	\par Example
	\code
	...
	int status;
	unsigned int device = 0;
	unsigned char plaintext[XLT_CIPHERTEXT_SIZE];
	unsigned char ciphertext[XLT_CIPHERTEXT_SIZE];

	//collect data to be encrypted
	...
	status = xlt_encrypt(device, plaintext, ciphertext);
	if (status == XLT_ERROR_SUCCESS){
		//ciphertext now contains the encryption of plaintext using AES 256 with key dongle_key passed to xlt_setup()
		...
	}
	...
	\endcode

	\par Another example just to show that xlt_decrypt() is the inverse of xlt_encrypt()
	\code
	...	
	int status;
	unsigned int device = 0;
	unsigned char plaintext[XLT_CIPHERTEXT_SIZE];
	unsigned char ciphertext[XLT_CIPHERTEXT_SIZE];
	unsigned char retplaintext[XLT_CIPHERTEXT_SIZE];

	//data to be encrypted (you can insert what you prefer)
	plaintext[0] = 0x01; plaintext[1] = 0xa2; plaintext[2] = 0x62; plaintext[3] = 0x31;
	plaintext[4] = 0x20; plaintext[5] = 0x36; plaintext[6] = 0x8b; plaintext[7] = 0x09;
	plaintext[8] = 0x45; plaintext[9] = 0x31; plaintext[10] = 0x7c; plaintext[11] = 0x18;
	plaintext[12] = 0x25; plaintext[13] = 0x81; plaintext[14] = 0x6b; plaintext[15] = 0xaa;

	status = xlt_encrypt(device, plaintext, ciphertext);
	if (status != XLT_ERROR_SUCCESS){
		printf("Encryption failed!\n");
	}
	else {
		//ciphertext now contains the encryption of plaintext using AES 256 with key dongle_key passed to xlt_setup()
		status = xlt_decrypt(device, ciphertext, retplaintext);
		if (status == XLT_ERROR_SUCCESS &&
			memcmp(plaintext, retplaintext, XLT_CIPHERTEXT_SIZE) == 0){
				printf("OK: returned the original plaintext\n");
		}
		else {
			printf("Decryption failed!\n");
		}
	}
    ...
	\endcode


 */
XLT_LINK int XLT_API xlt_encrypt(unsigned int device, const unsigned char* plaintext, unsigned char* ciphertext);


/**
\deprecated
Perform AES-256 decryption.
 \param[in] device device index for the selection of a specific XLight device. This value runs from 0 to ::XLT_DEVICE_EXT_MAX -1.
 \param[in] ciphertext points to the buffer of length ::XLT_CIPHERTEXT_SIZE containing the ciphertext to be decrypted.
 \param[out] plaintext points to the buffer of length ::XLT_CIPHERTEXT_SIZE containing the result of the decryption.
 \return returns ::XLT_ERROR_SUCCESS on success, an \ref xlt_Errors "error code" on failure.
 \remark this function is the inverse of xlt_encrypt(), that is from ciphertext it returns the original plaintext passed to xlt_encrypt().
 \note the decryption function uses as cryptographic key the <i>Dongle Key</i> entry set by xlt_setup().

	\par Example
	\code
	...
	int status;
	unsigned int device = 0;
	unsigned char ciphertext[XLT_CIPHERTEXT_SIZE];
	unsigned char ret_plaintext[XLT_CIPHERTEXT_SIZE];

	//collect data to be decrypted
	...
	status = xlt_decrypt(device, ciphertext, ret_plaintext);
	if (status == XLT_ERROR_SUCCESS){
		//ret_plaintext now contains the decryption of ciphertext using AES 256 with key dongle_key set passed to xlt_setup()
		...
	}
	...
	\endcode

 */
XLT_LINK int XLT_API xlt_decrypt(unsigned int device, const unsigned char* ciphertext, unsigned char* plaintext);


/**
\deprecated
Challenge-Response computation based on AES-256.
The protected software send a value and check that the outcome is as expected.
 \param[in] device device index for the selection of a specific XLight device. This value runs from 0 to ::XLT_DEVICE_EXT_MAX -1.
 \param[in] challenge points to the buffer of length ::XLT_CIPHERTEXT_SIZE containing the challenge data.
 \param[out] response points to the buffer of length ::XLT_CIPHERTEXT_SIZE receiving the response.
 \return returns ::XLT_ERROR_SUCCESS on success, an \ref xlt_Errors "error code" on failure.
 \note the Challenge-Response mechanism uses as cryptographic key the <i>cr_key</i> (<i>Challenge Response Key</i>) entry set by xlt_setup().
 \remark the challenge response mechanism is a sort of proof of identity without exposing details to eavesdroppers on the USB communication or
 on the dll interface. It is based onto the AES-256 encryption and the verifier inside the protected program must know the key used by the
 device. A good hacker debugging the code can come up to the encryption key, so the best policy is to make this task hard trying to hide
 the key: for instance preparing the challenge and evaluating the response far from the code communicating with the dongle. The example below is not a good
 example from this point of view and it must be considered just as an example. xlt_challenge() works in the same way of xlt_encrypt() but using a different AES key.

 \note Another possible and better way is to calculate many pairs challenge-presponse in a safe environment (i.e. not in the protected application)
 and use such pairs to verify the response of the dongle. This method avoid the exposure of the <i>Challenge Response Key</i>.


	\par Example
	\code
	...
	#include <windows.h>
	#include "aes.h"
	...
	int status;
	unsigned int device = 0;
	unsigned char challenge[XLT_CIPHERTEXT_SIZE];
	unsigned char response[XLT_CIPHERTEXT_SIZE];
	unsigned char expected_response[XLT_CIPHERTEXT_SIZE];
	unsigned char cr_key[XLT_KEY_SIZE];
	volatile unsigned char* c;
	int i;
	aes_ctx aes_ctx; 


	//compute the challenge (if possible always a new value)
	srand(GetTickCount());
	for (i=0; i < XLT_CIPHERTEXT_SIZE; i++)
		//it's better to use a cryptographic safe random generator (rand() is easy but not good)
		challenge[i] = (unsigned char)rand();
	

	//challenge uses AES 256 encryption algorithm with key cr_key passed to xlt_setup()
	status = xlt_challenge(device, challenge, response);
	if (status != XLT_ERROR_SUCCESS){
		printf("Challenge Response failed!\n");
		//take the due action (halt execution)
	}
	else {
		//check if the response is as expected (if not, the attached device is not what you expect to be!)
		// we strongly recommend to perform the following check far and later from the xlt_challenge() call above, 
		//this makes the hacking job harder.
		for(i = 0; i < XLT_KEY_SIZE; i++){		
			cr_key[i]=(unsigned char)i*2;
		}
		//AES encryption key setup
		aes_setkey(cr_key, XLT_KEY_SIZE, aes_enc, &aes_ctx);
		c = cr_key;
		for(i = 0; i < XLT_KEY_SIZE; i++){//cleanup
			*c++ = 0;
		}
		
		//AES encryption execution prototype:
		//int aes_encrypt(const unsigned char* plaintext, unsigned char* ciphertext, const aes_ctx* ctx);
		aes_encrypt(challenge, expected_response, &aes_ctx);
		c = (unsigned char*) &aes_ctx;
		for(i = 0; i < sizeof(aes_ctx); i++){//cleanup
			*c++ = 0;
		}

		if (memcmp(expected_response, response, XLT_CIPHERTEXT_SIZE) != 0){
			//the device has not computed what we expected
			printf("Challenge Response failed!\n");
			//take the due action (halt execution)
		}
	}
	...
	\endcode
 */
XLT_LINK int XLT_API xlt_challenge(unsigned int device, const unsigned char* challenge, unsigned char* response);

/**
 * \ingroup xlt_aes
Load on an XLight device the session AES key to be used for AES session encryption functions.
See \ref AES_Session_Key for an introduction on <i>Session Key</i> protection.

 \param[in] device device index for the selection of a specific XLight device. This value runs from 0 to ::XLT_DEVICE_EXT_MAX -1.
 \param[in] key_index index of the key to be used. This value runs from 0 to ::XLT_SESSION_NUMBER_OF_KEYS -1.
 \param[in] wrapped_key points to the buffer of length ::XLT_KEY_SIZE containing the <i>Session Key</i> encrypted with <i>Dongle Key</i>.
 \return returns ::XLT_ERROR_SUCCESS on success, an \ref xlt_Errors "error code" on failure.

 This function must be used to set the AES key that will be used by xlt_session_encrypt() and xlt_session_decrypt(). This cryptographic key
 must be passed in encrypted (wrapped) form depending on the <i>Dongle Key<i>. In oreder to produce the wrapped form of the <i>Session Key</i> use xlt_session_wrap_key().
 It is possible to set ::XLT_SESSION_NUMBER_OF_KEYS sessin key simultaneously, with key_index it is possible to refer to one of these keys.

 \note a <i>Session Key</i> is not permanent, it resides on the device as long as the dongle is plugged and powered, once the dongle is 
 removed the key is deleted. This means that it must be loaded every time it must be used. The default value, that is just after the device is plugged,
 is a zero buffer.
See \ref Session_KeyProtection "here" for a source code example using this function.
<p><b>Supported version</b>: this function is available on XLight devices version 2.0 or later.
 \sa xlt_session_encrypt(), xlt_session_decrypt() and xlt_session_wrap_key().
 */
XLT_LINK int XLT_API xlt_session_set_key(unsigned int device, unsigned int key_index, const unsigned char* wrapped_key);

/**
\ingroup xlt_aes
Encrypt data using a <i>Session Key</i>.
See \ref AES_Session_Key for an introduction on <i>Session Key</i> protection.
 \param[in] device device index for the selection of a specific XLight device. This value runs from 0 to ::XLT_DEVICE_EXT_MAX -1.
 \param[in] key_index index of the key to be used. This value runs from 0 to ::XLT_SESSION_NUMBER_OF_KEYS -1.
 \param[in] plaintext points to the buffer of length ::XLT_CIPHERTEXT_SIZE containing the data to be encrypted
 \param[out] ciphertext points to the buffer of length ::XLT_CIPHERTEXT_SIZE that will receive the encrypted data.
 \return returns ::XLT_ERROR_SUCCESS on success, an \ref xlt_Errors "error code" on failure.

 This function performs AES-256 encryption of a plaintext of length ::XLT_CIPHERTEXT_SIZE and inserts the ciphertext result in a buffer of the same length.
 The AES key is one of the eight <i>Session Keys</i> specified by the index <i>key_index</i>, and the corrisponding key was previously set by the xlt_session_decrypt() function.

 See \ref Session_KeyProtection "here" for a source code example using this function.
 <p><b>Supported version</b>: this function is available on XLight devices version 2.0 or later.
 \sa xlt_session_decrypt(), xlt_session_decrypt and xlt_session_wrap_key().
 */
XLT_LINK int XLT_API xlt_session_encrypt(unsigned int device, unsigned int key_index, const unsigned char* plaintext, unsigned char* ciphertext);

/**
* \ingroup xlt_aes
Decrypt data using a <i>Session Key</i>.
See \ref AES_Session_Key for an introduction on <i>Session Key</i> protection.
 \param[in] device device index for the selection of a specific XLight device. This value runs from 0 to ::XLT_DEVICE_EXT_MAX -1.
 \param[in] key_index index of the key to be used. This value runs from 0 to ::XLT_SESSION_NUMBER_OF_KEYS -1.
 \param[in] ciphertext points to the buffer of length ::XLT_CIPHERTEXT_SIZE containing the data to be decrypted.
 \param[out] plaintext points to the buffer of length ::XLT_CIPHERTEXT_SIZE that will receive the decrypted data.
 \return returns ::XLT_ERROR_SUCCESS on success, an \ref xlt_Errors "error code" on failure.

 This function performs AES-256 decryption of a ciphertext buffer with length of the block of the AES algorithm, that is a length of ::XLT_CIPHERTEXT_SIZE.
 The used key was set by a previous call of xlt_session_set_key().
<p><b>Supported version</b>: this function is available on XLight devices version 2.0 or later.
  \sa xlt_session_wrap_key().
 */
XLT_LINK int XLT_API xlt_session_decrypt(unsigned int device, unsigned int key_index, const unsigned char* ciphertext, unsigned char* plaintext);

/**
* \ingroup xlt_aes
Wraps a <i>Session Key</i>. 
See \ref AES_Session_Key for an introduction on <i>Session Key</i> protection.
 \param[in] session_key points to the AES key that will be used by xlt_session_encrypt() and xlt_session_decrypt(). It's length is of ::XLT_KEY_SIZE bytes.
 \param[in] dongle_key points to the value of the <i>Dongle Key</i> set up by xlt_setup() function.
 \param[out] wrapped_key points to a memory buffer of length ::XLT_KEY_SIZE that will receive the wrapped version of key.
\return returns ::XLT_ERROR_SUCCESS on success, an \ref xlt_Errors "error code" on failure.

\note never use this function onto the protected software, in particular, never insert the <i>Dongle Key</i> into the protected software.
This is an utility software to compute the wrapped version of a <i>Session Key</i> and must be done in an utility software not distributed to the 
final user. The <i>Wrapped Key</i> must be used onto the protected software and loaded onto the XLight dongle using xlt_session_set_key().
\note this function doesn't require any XLight device to be plugged in.

See \ref Session_KeyPreliminary "here" for a source code example using this function.

<p><b>Supported version</b>: this function is available on XLight devices version 2.0 or later.
\sa xlt_session_set_key().
*/
XLT_LINK int XLT_API xlt_session_wrap_key(const unsigned char* session_key, const unsigned char* dongle_key, unsigned char* wrapped_key);

/**
* \ingroup xlt_rsa
Generate an RSA key.
See \ref RSA_Protection for an introduction on the RSA protection in XLight.
\param[in] bit_size the length in bit of the key to generate. The possible values are ::XLT_RSA_512_BIT_SIZE and ::XLT_RSA_1024_BIT_SIZE.
\param[out] private_key points to the buffer that will receive the generated RSA private key formatted with XLight RSA Key format (\ref RSA_format).
\param[in] private_key_size size of the private_key buffer. The size for a 1024 bit key is ::XLT_RSA_1024_PRIV_KEY_SIZE and the size for a 512 bit key is ::XLT_RSA_512_PRIV_KEY_SIZE.
\param[out] p_private_key_len points to an unsigned integer that will receive the actual length of the generated formatted private key.
\param[out] public_key points to the buffer that will receive the generated RSA public key formatted in XLight RSA Key format (\ref RSA_format).
If this parameter is NULL the public key is not retrieved.
\param[in] public_key_size size of the public_key buffer. The size for a 1024 bit key is ::XLT_RSA_1024_PUB_KEY_SIZE and the size for a 512 bit key is ::XLT_RSA_512_PUB_KEY_SIZE.
\param[out] p_public_key_len points to an unsigned integer that will receive the actual length of the generated formatted public key.
\return ::XLT_ERROR_SUCCESS on success, an \ref xlt_Errors "error code" on failure.

\note this is an utility function that must be never used onto the protected software. Its purpose is RSA key generation and may be substituted
by other software doing the same task. There are plenty of source code available in internet doing RSA key generation.
<p><b>Supported version</b>: this function is available on XLight devices version 2.0 or later.
\sa xlt_rsa_wrap_privkey().
*/
XLT_LINK int XLT_API xlt_rsa_generate_key(unsigned int bit_size, unsigned char* private_key, unsigned int private_key_size, unsigned int* p_private_key_len,
										  unsigned char* public_key, unsigned int public_key_size, unsigned int* p_public_key_len);

/**
* \ingroup xlt_rsa
Wraps an RSA key.
See \ref RSA_Protection for an introduction on the RSA protection in XLight.
\param[in] private_key points to a buffer containing a formatted private key.
\param[in] private_key_length length of the RSA formatted key (\ref RSA_format).
\param[in] dongle_key points to a buffer containing <i>Dongle Key</i>.
\param[out] wrapped_key points to the buffer that will receive an encryption of the RSA private key (wrapped).
\param[in] wrapped_key_len the length of <i>Wrapped Key</i> pointed by wrapped_key. The length of a <i>Wrapped Key</i> must be ::XLT_RSA_1024_WRAPPED_KEY_SIZE for a 1024-bit key and ::XLT_RSA_512_WRAPPED_KEY_SIZE for a 512-bit key.
\return ::XLT_ERROR_SUCCESS on success, an \ref xlt_Errors "error code" on failure.

\note this is an utility function that must be never used onto the protected software. Its purpose is to encrypt an RSA private key for protecting its 
content. The produced <i>Wrapped Key</i> may reside into a protected software or exposed to the public access without revealing its real content.
In order to insert a private key onto the device the <i>Wrapped Key</i> must be passed to the function xlt_rsa_set_privkey().

<p><b>Supported version</b>: this function is available on XLight devices version 2.0 or later.
\sa xlt_rsa_set_privkey()
*/
XLT_LINK int XLT_API xlt_rsa_wrap_privkey(const unsigned char* private_key, unsigned int private_key_length, const unsigned char* dongle_key, unsigned char* wrapped_key, unsigned int wrapped_key_len);

/**
* \ingroup xlt_rsa
Wraps an RSA key.
As xlt_rsa_wrap_privkey() function but with the addition to bind a specific recipient XLight device by its serial number.
See \ref RSA_Protection for an introduction on the RSA protection in XLight.
\param[in] private_key points to a buffer containing a formatted private key.
\param[in] private_key_length length of the RSA formatted key (\ref RSA_format).
\param[in] dongle_key points to a buffer containing <i>Dongle Key</i>.
\param[in] sn the serial number of the destination XLight device.
\param[out] wrapped_key points to the buffer that will receive an encryption of the RSA private key (wrapped).
\param[in] wrapped_key_len the length of <i>Wrapped Key</i> pointed by wrapped_key. The length of a <i>Wrapped Key</i> must be ::XLT_RSA_1024_WRAPPED_KEY_SIZE for a 1024-bit key and ::XLT_RSA_512_WRAPPED_KEY_SIZE for a 512-bit key.
\return ::XLT_ERROR_SUCCESS on success, an \ref xlt_Errors "error code" on failure.

\note this is an utility function that must be never used onto the protected software. Its purpose is to encrypt an RSA private key for protecting its 
content. The produced <i>Wrapped Key</i> may reside into a protected software or exposed to the public access without revealing its real content.
In order to insert a private key onto the device the <i>Wrapped Key</i> must be passed to the function xlt_rsa_set_privkey().

<p><b>Supported version</b>: this function is available on XLight devices version 2.4 or later.
\sa xlt_rsa_wrap_privkey()
*/
XLT_LINK int XLT_API xlt_rsa_wrap_privkey_sn(const unsigned char* private_key, unsigned int private_key_length, const unsigned char* dongle_key, unsigned int sn, unsigned char* wrapped_key, unsigned int wrapped_key_len);

/**
* \ingroup xlt_rsa
Load an RSA private key onto an XLight device.
See \ref RSA_Protection for an introduction on the RSA protection in XLight.
\param[in] device device index for the selection of a specific XLight device. This value runs from 0 to ::XLT_DEVICE_EXT_MAX -1.
\param[in] wrapped_key points to the buffer containing the wrapped RSA key to be inserted into ther XLight device.
\param[in] wrapped_key_length the length of the <i>Wrapped Key</i> data.
\return ::XLT_ERROR_SUCCESS on success, an \ref xlt_Errors "error code" on failure.

\note on an XLight device it is possible to store two RSA keys: one 1024 bit key and one 512 bit key. The bit length reppresent the length of its
"modulus", not the length of the data containing the key (see \ref RSA_format). The device recognizes the two different key types and write them in their reserved memory place.

The RSA key received from this function is not in clear form, but encrypted by the function xlt_rsa_wrap_privkey().
In this way the RSA private key can be set by the protected program without exposing any relevant data, and hence preventing a hacker to understand the values (which would ruin all the security protocol based on RSA).

\note an RSA key is present onto the device also after device removal because it is written in a non volatile memory, 
nevertheless it can be always overwritten with a new one.
<p><b>Supported version</b>: this function is available on XLight devices version 2.0 or later.
*/
XLT_LINK int XLT_API xlt_rsa_set_privkey(unsigned int device, const unsigned char* wrapped_key, unsigned int wrapped_key_length);

/**
* \ingroup xlt_rsa
Performs RSA encryption.
\deprecated just use for test purpose

See \ref RSA_Protection for an introduction on the RSA protection in XLight.
\param[in] public_key points to the buffer containing the formatted public key used for the encryption.
\param[in] public_key_len length of the formatted public key. The allowed values are ::XLT_RSA_1024_PUB_KEY_SIZE and ::XLT_RSA_512_PUB_KEY_SIZE.
\param[in] plaintext points to the buffer containing the data to be encrypted.
\param[in] plaintext_ciphertext_length the length of plaintext and the size of the buffer pointed by ciphertext. 
The allowed values for this argument are ::XLT_RSA_1024_PLAINTEXT_SIZE and ::XLT_RSA_512_PLAINTEXT_SIZE, if the plaintext is shorter it must be 
copied into a buffer of the proper length and zero padded up to its overall length.
\param[out] ciphertext points to the buffer that will receive the result of the encryption.
\return ::XLT_ERROR_SUCCESS on success, an \ref xlt_Errors "error code" on failure.
\note this function is present for test purpose, never use it in the application protected with XLight.
<p><b>Supported version</b>: this function is available on XLight devices version 2.0 or later.
*/
XLT_LINK int XLT_API xlt_never_use_this_rsa_encrypt(const unsigned char* public_key, unsigned int public_key_len, const unsigned char* plaintext, unsigned int plaintext_ciphertext_length, unsigned char* ciphertext);

/**
* \ingroup xlt_rsa
Performs a software RSA decryption.
\deprecated just use for test purpose

See \ref RSA_Protection for an introduction on the RSA protection in XLight.
\param[in] private_key points to a buffer containing the formatted private RSA key to be used.
\param[in] private_key_len length of the formatted private key. The allowed values are ::XLT_RSA_1024_PRIV_KEY_SIZE and ::XLT_RSA_512_PRIV_KEY_SIZE.
\param[in] ciphertext points to the buffer containing the data to be decrypted.
\param[in] ciphertext_plaintext_length the length of the data to be decrypted, and the size of the receiving buffer.
The allowed values for this argument are ::XLT_RSA_1024_PLAINTEXT_SIZE and ::XLT_RSA_512_PLAINTEXT_SIZE, if the plaintext is shorter it must be 
copied into a buffer of the proper length and zero padded up to its overall length.
\param[out] plaintext points to the buffer that will receive the result of the decryption.
\return ::XLT_ERROR_SUCCESS on success, an \ref xlt_Errors "error code" on failure.
<p><b>Supported version</b>: this function is available on XLight devices version 2.0 or later.
*/
XLT_LINK int XLT_API xlt_never_use_this_rsa_sw_decrypt(const unsigned char* private_key, unsigned int private_key_len, const unsigned char* ciphertext, unsigned int ciphertext_plaintext_length, unsigned char* plaintext);

/**
* \ingroup xlt_rsa
Runs an RSA decryption onto an XLight device.
See \ref RSA_Protection for an introduction on the RSA protection in XLight.
\param[in] device device index for the selection of a specific XLight device. This value runs from 0 to ::XLT_DEVICE_EXT_MAX -1.
\param[in] ciphertext points to the buffer containing the data to be decrypted.
\param[in] ciphertext_plaintext_length the length of the data to be decrypted, and the size of the receiving buffer.
The allowed values for this argument are ::XLT_RSA_1024_PLAINTEXT_SIZE and ::XLT_RSA_512_PLAINTEXT_SIZE, if the plaintext is shorter it must be 
copied into a buffer of the proper length and zero padded up to its overall length (see \ref RSA_format).
\param[out] plaintext points to the buffer that will receive the result of the decryption.
\return ::XLT_ERROR_SUCCESS on success, an \ref xlt_Errors "error code" on failure.
\note the length of the ciphertext buffer must be the same of the plaintext. If the length is ::XLT_RSA_1024_PLAINTEXT_SIZE the 1024-bit key is used,
if the length is ::XLT_RSA_512_PLAINTEXT_SIZE the 512-bit key is used, for any other value an error is returned.
<p><b>Supported version</b>: this function is available on XLight devices version 2.0 or later.
*/
XLT_LINK int XLT_API xlt_rsa_decrypt(unsigned int device, const unsigned char* ciphertext, unsigned int ciphertext_plaintext_length, unsigned char* plaintext);

/**
\ingroup xlt_bank
Lock a memory bank.

\note <b> this function produces an irreversible setting onto the XLight device, hence use it very carefully.</b>

See \ref locked_memory.
\param[in] device device index for the selection of a specific XLight device. This value runs from 0 to ::XLT_DEVICE_EXT_MAX -1.
\param[in] password points to a buffer of length ::XLT_PASSWORD_SIZE. It contains the password assigned to the device with xlt_setup().
\param[in] bank the index of the memory bank that must be locked.
\param[in] group_number the group number to be assigned to the locking bank.
\return returns ::XLT_ERROR_SUCCESS on success, an \ref xlt_Errors "error code" on failure.

A locked memory bank can be written only using encrypted commands created by xlt_set_write_locked_group_check() or xlt_set_write_locked_serial_check() 
and performed by xlt_write_locked().
\note the group number is intended to define subgroups that must be treated in different ways. If there is no reason to create such differentiation
it must be inserted the same number for all devices, say 0.
The grouping allows to create a single encrypted command to modify the memory content of locked banks onto a large number of devices.

\remark it is not useful to set a different group number for every device because it is already possible create a command for a single device by using its serial number.

\note a locked bank can always be read using the xlt_read() function, but can't be written with xlt_write() any more.
A locked memory bank is subject to a restriction in its dimension: only ::XLT_LOCKED_BANK_DATA_LENGTH will be freely available for reading and writing.
The remaining bytes are used by the locking mechanism management.

\sa xlt_bank_lock2(), xlt_set_write_locked_group_check(), xlt_set_write_locked_serial_check()
*/
XLT_LINK int XLT_API xlt_bank_lock(unsigned int device, const unsigned char* password, unsigned int bank, unsigned int group_number);

/**
\ingroup xlt_bank
Lock a memory bank in advanced mode (<i>Lock2</i>).

\note <b> this function produces an irreversible setting onto the XLight device, hence use it very carefully.</b>

See \ref locked_memory.
\param[in] device device index for the selection of a specific XLight device. This value runs from 0 to ::XLT_DEVICE_EXT_MAX -1.
\param[in] password points to a buffer of length ::XLT_PASSWORD_SIZE. It contains the password assigned to the device with xlt_setup().
\param[in] bank the index of the memory bank that must be locked.
\param[in] group_number the group number to be assigned to the locking bank.
\return returns ::XLT_ERROR_SUCCESS on success, an \ref xlt_Errors "error code" on failure.

A locked2 memory bank can be written only using encrypted commands created by xlt_set_write_locked2_group_check() or xlt_set_write_locked2_serial_check() 
and performed by xlt_write_locked().
\note the group number is intended to define subgroups that must be treated in different ways. If there is no reason to create such differentiation
it must be inserted the same number for all devices, say 0.
The grouping allows to create a single encrypted command to modify the memory content of locked banks onto a large number of devices.

\remark it is not useful to set a different group number for every device because it is already possible create a command for a single device by using its serial number.

\note a locked bank can always be read using the xlt_read() function, but can't be written with xlt_write() any more.
A locked2 memory bank is subject to a restriction in its dimension: only ::XLT_LOCKED_BANK_DATA_LENGTH will be freely available for reading and writing.
The remaining bytes are used by the locking mechanism management.
<p><b>Supported version</b>: this function is available on XLight devices version 1.01 or later.
\sa xlt_set_write_locked2_group_check(), xlt_set_write_locked2_serial_check()
*/
XLT_LINK int XLT_API xlt_bank_lock2(unsigned int device, const unsigned char* password, unsigned int bank, unsigned int group_number);

/**
\ingroup xlt_bank
Perform a write operation in a locked bank (both normal and advanced <i>Lock2</i> mode).

See \ref locked_memory.
\param[in] device device index for the selection of a specific XLight device. This value runs from 0 to ::XLT_DEVICE_EXT_MAX -1.
\param[in] bank the index of the memory bank that must be written.
\param[in] transfer_data points to a buffer of size ::XLT_LOCKED_TRANSFER_DATA containing the values computed by xlt_set_write_locked_serial_check() or 
xlt_set_write_locked_group_check().
\return returns ::XLT_ERROR_SUCCESS on success, an \ref xlt_Errors "error code" on failure.
\sa xlt_set_write_locked_serial_check(), xlt_set_write_locked_group_check().
*/
XLT_LINK int XLT_API xlt_write_locked(unsigned int device, unsigned int bank, const unsigned char* transfer_data);


/**
\ingroup xlt_bank
Perform a read operation in a locked bank (both normal and advanced <i>Lock2</i> mode).

See \ref locked_memory.
\param[in] device device index for the selection of a specific XLight device. This value runs from 0 to ::XLT_DEVICE_EXT_MAX -1.
\param[in] bank the index of the memory bank that must be read.
\param[out] transfer_data points to a buffer of size ::XLT_LOCKED_TRANSFER_DATA that will receive the content of the memory bank in encrypted form.
\return returns ::XLT_ERROR_SUCCESS on success, an \ref xlt_Errors "error code" on failure.
\remark in order to get the data in plain form the function xlt_decrypt_locked2_data() must be used.
\note a locked bank can always be read using the xlt_read() function, while this function doesn't need the use
of <i>password</i>, but its outcome can't be used as is, because it needs decryption.

A locked memory bank is subjected to a restriction in its dimension: only ::XLT_LOCKED_BANK_DATA_LENGTH will be freely available for reading and writing.
The remaining bytes are used by the locking mechanism management.
\sa xlt_decrypt_locked2_data().
*/
XLT_LINK int XLT_API xlt_read_locked(unsigned int device, unsigned int bank, unsigned char* transfer_data);


/**
\ingroup xlt_bank
Encrypt the buffer to be written into a locked bank of a specific XLight device.
This data can be written only once and only in the device with a given serial number, provided that the destination bank is locked (see xlt_bank_lock2()).

See \ref locked_memory.
\param[in] data points to a buffer of length ::XLT_LOCKED_BANK_DATA_LENGTH, that contains the value that must be written onto a locked bank.
\param[in] bank specify the index of the memory bank that must written.
\param[in] new_counter new counter value: this value must be greater than the counter value currently contained into the locked bank.
\param[in] serial the serial number of the XLight device target.
\param[in] dongle_key points to a buffer of length ::XLT_KEY_SIZE. It contains the AES-256 key <i>Dongle Key</i> set during xlt_getinfo() call.
\param[out] transfer_data points to a buffer of size ::XLT_LOCKED_TRANSFER_DATA that will receive the encrypted write command that will be 
applied onto the XLight device via the xlt_write_locked() function.
to the XLight device with the xlt_write() function in order to write <i>data</i> into a locked bank.
\return returns ::XLT_ERROR_SUCCESS on success, an \ref xlt_Errors "error code" on failure.
 
\remark this function is to be considered as an utility not to be used diretly by the protected software.
It can be used by the vendor of the protected software in order to remotely update the locked memory of a device.
In this scenario the <i>Dongle Key</i> key must never be used onto the protected software, but used only to generate update for the device memory.
This way it is possible to remotely update the content of a locked bank. A locked bank can be read normally by a protected application using xlt_read(), so
this remote update technique can be used, for instance, for license management purposes.
\sa xlt_set_write_locked_group_check(), xlt_write_locked(), xlt_read_locked(), xlt_decrypt_locked_data().
*/
XLT_LINK int XLT_API xlt_set_write_locked_serial_check(const unsigned char* data, unsigned int bank, unsigned int new_counter, unsigned int serial, const unsigned char* dongle_key , unsigned char* transfer_data);

/**
\ingroup xlt_bank
Encrypt the buffer to be written into a bank locked with <i>Lock2</i> of a specific XLight device.
This data can be written only once and only in the device with a given serial number, provided that the destination bank is locked (see xlt_bank_lock2()).

See \ref locked_memory.
\param[in] data points to a buffer of length ::XLT_LOCKED_BANK_DATA_LENGTH, that contains the value that must be written onto a locked bank.
\param[in] bank specify the index of the memory bank that must written.
\param[in] new_counter new counter value: this value must be greater than the counter value currently contained into the locked bank.
\param[in] serial the serial number of the XLight device target.
\param[in] dongle_key points to a buffer of length ::XLT_KEY_SIZE. It contains the AES-256 key <i>Dongle Key</i> set during xlt_getinfo() call.
\param[out] transfer_data points to a buffer of size ::XLT_LOCKED_TRANSFER_DATA that will receive the encrypted write command that will be 
applied onto the XLight device via the xlt_write_locked() function.
to the XLight device with the xlt_write() function in order to write <i>data</i> into a locked bank.
\return returns ::XLT_ERROR_SUCCESS on success, an \ref xlt_Errors "error code" on failure.
 
\remark this function is to be considered as an utility not to be used diretly by the protected software.
It can be used by the vendor of the protected software in order to remotely update the locked memory of a device.
In this scenario the <i>Dongle Key</i> key must never be used onto the protected software, but used only to generate update for the device memory.
This way it is possible to remotely update the content of a locked bank. A locked bank can be read normally by a protected application using xlt_read(), so
this remote update technique can be used, for instance, for license management purposes.
<p><b>Supported version</b>: this function is available on XLight devices version 1.01 or later.
\sa xlt_set_write_locked2_group_check(), xlt_write_locked(), xlt_read_locked(), xlt_decrypt_locked2_data().
*/
XLT_LINK int XLT_API xlt_set_write_locked2_serial_check(const unsigned char* data, unsigned int bank, unsigned int new_counter, unsigned int serial, const unsigned char* dongle_key , unsigned char* transfer_data);

/**
\ingroup xlt_bank
Encrypt the buffer to be written into a locked bank belonging to an XLight devices of a given group.
This data can be written only once provided that the destination bank is locked (see xlt_bank_lock()).

See \ref locked_memory.
\param[in] data points to a buffer of length ::XLT_LOCKED_BANK_DATA_LENGTH, that contains the value that must be written into the locked bank.
\param[in] bank specify the index of the memory bank that must written.
\param[in] new_counter new counter value: this value must be greater than the counter value currently contained into the locked bank.
\param[in] group_number the group number of the XLight devices for which the encrypted buffer is prepared.
\param[in] dongle_key points to a buffer of length ::XLT_KEY_SIZE. It contains the AES-256 key <i>Dongle Key</i> set during xlt_getinfo() call.
\param[out] transfer_data points to a buffer of size ::XLT_LOCKED_TRANSFER_DATA that will receive the encrypted write command that will be 
applied onto the XLight device via the xlt_write_locked() function.
\return returns ::XLT_ERROR_SUCCESS on success, an \ref xlt_Errors "error code" on failure.
 
\remark the group number correspond to what is set on the dongle by xlt_bank_lock(). 
It is intended to define subgroups of devices each of them must be treated in the same way. 
For further notices see the comments of xlt_set_write_locked_serial_check(), they hold also for this function.
*/
XLT_LINK int XLT_API xlt_set_write_locked_group_check(const unsigned char* data, unsigned int bank, unsigned int new_counter, unsigned int group_number, const unsigned char* dongle_key, unsigned char* transfer_data);

/**
\ingroup xlt_bank
Encrypt the buffer to be written into a bank locked with <i>Lock2</i> belonging to an XLight devices of a given group.
This data can be written only once provided that the destination bank is locked (see xlt_bank_lock2()).

See \ref locked_memory.
\param[in] data points to a buffer of length ::XLT_LOCKED_BANK_DATA_LENGTH, that contains the value that must be written into the locked bank.
\param[in] bank specify the index of the memory bank that must written.
\param[in] new_counter new counter value: this value must be greater than the counter value currently contained into the locked bank.
\param[in] group_number the group number of the XLight devices for which the encrypted buffer is prepared.
\param[in] dongle_key points to a buffer of length ::XLT_KEY_SIZE. It contains the AES-256 key <i>Dongle Key</i> set during xlt_getinfo() call.
\param[out] transfer_data points to a buffer of size ::XLT_LOCKED_TRANSFER_DATA that will receive the encrypted write command that will be 
applied onto the XLight device via the xlt_write_locked() function.
\return returns ::XLT_ERROR_SUCCESS on success, an \ref xlt_Errors "error code" on failure.
 
\remark the group number correspond to what is set on the dongle by xlt_bank_lock2(). 
It is intended to define subgroups of devices each of them must be treated in the same way. 
For further notices see the comments of xlt_set_write_locked_serial_check(), they hold also for this function.
<p><b>Supported version</b>: this function is available on XLight devices version 1.01 or later.
*/
XLT_LINK int XLT_API xlt_set_write_locked2_group_check(const unsigned char* data, unsigned int bank, unsigned int new_counter, unsigned int group_number, const unsigned char* dongle_key, unsigned char* transfer_data);

/**
\ingroup xlt_bank
Retrieve the data in clear form of the content of a locked memory bank.

See \ref locked_memory.
\param[in] transfer_data points to a buffer of length ::XLT_LOCKED_TRANSFER_DATA.
\param[in] dongle_key points to a buffer of length ::XLT_KEY_SIZE containing the dangle_key key set by xlt_setup().
\param[out] data points to a buffer of length ::XLT_BANK_SIZE that will receice the decrypted value.
\return returns ::XLT_ERROR_SUCCESS on success, an \ref xlt_Errors "error code" on failure.

\remark xlt_decrypt_locked_data() retrieves the data in clear form of the content of a memory bank collected with a previous xlt_read_locked() call.
xlt_decrypt_locked_data() and xlt_read_locked() are used in a server client memory bank read operation. The xlt_read_locked() doesn't need of any password
and cryptographic key to be used but produces an encrypted buffer that can be understood only by the holder of the <i>Dongle Key</i> crypto-key.
xlt_read_locked() can be executed by non trusted people to collect information. Afterwards xlt_decrypt_locked_data() allows the authorized parts to decrypt
and read the content of the memory bank.

The buffer returned by xlt_decrypt_locked_data() is ::XLT_KEY_SIZE bytes long, but only the first ::XLT_LOCKED_BANK_DATA_LENGTH bytes are the significant data
that can be written and used by the application. The remaining bytes are managed internally by the library and used for the 'locked bank' management.
These bytes convey information that may be retrieved using xlt_get_info_from_locked_bank(), such information are necessary for writing inside a locked bank.
\sa xlt_read_locked(), xlt_get_info_from_locked_bank() 
*/
XLT_LINK int XLT_API xlt_decrypt_locked_data(const unsigned char* transfer_data, const unsigned char* dongle_key, unsigned char* data);

/**
\ingroup xlt_bank
Retrieve the data in clear form of the content of a locked with <i>Lock2</i> memory bank.

See \ref locked_memory.
\param[in] transfer_data points to a buffer of length ::XLT_LOCKED_TRANSFER_DATA.
\param[in] dongle_key points to a buffer of length ::XLT_KEY_SIZE containing the dangle_key key set by xlt_setup().
\param[out] data points to a buffer of length ::XLT_BANK_SIZE that will receice the decrypted value.
\return returns ::XLT_ERROR_SUCCESS on success, an \ref xlt_Errors "error code" on failure.

\remark xlt_decrypt_locked2_data() retrieves the data in clear form of the content of a memory bank collected with a previous xlt_read_locked() call.
xlt_decrypt_locked2_data() and xlt_read_locked() are used in a server client memory bank read operation. The xlt_read_locked() doesn't need of any password
and cryptographic key to be used but produces an encrypted buffer that can be understood only by the holder of the <i>Dongle Key</i> crypto-key.
xlt_read_locked() can be executed by non trusted people to collect information. Afterwards xlt_decrypt_locked2_data() allows the authorized parts to decrypt
and read the content of the memory bank.

The buffer returned by xlt_decrypt_locked2_data() is ::XLT_KEY_SIZE bytes long, but only the first ::XLT_LOCKED_BANK_DATA_LENGTH bytes are the significant data
that can be written and used by the application. The remaining bytes are managed internally by the library and used for the 'locked bank' management.
These bytes convey information that may be retrieved using xlt_get_info_from_locked_bank(), such information are necessary for writing inside a locked bank.
<p><b>Supported version</b>: this function is available on XLight devices version 1.01 or later.
\sa xlt_read_locked(), xlt_get_info_from_locked_bank() 
*/
XLT_LINK int XLT_API xlt_decrypt_locked2_data(const unsigned char* transfer_data, const unsigned char* dongle_key, unsigned char* data);

/**
\ingroup xlt_bank
Return information of a locked bank (both normal and advanced <i>Lock2</i> mode).

See \ref locked_memory.
\param[in] data points to a buffer of length ::XLT_BANK_SIZE, that contains the value retrieved from a locked bank by xlt_read() or xlt_decrypt_locked_data().
\param[out] pbank points to an unsigned int that will contain the bank number to which the data belongs. This parameter is optional and may be set to NULL.
\param[out] pcounter points to an unsigned int that will contain the current counter field of the locked bank. This parameter is optional and may be set to NULL.
\param[out] pserial points to an unsigned int that will contain the serial number of the locked bank. This parameter is optional and may be set to NULL.
\param[out] pgroup_number points to an unsigned int that will contain the group number of the locked bank. This parameter is optional and may be set to NULL.
\return returns ::XLT_ERROR_SUCCESS on success, an \ref xlt_Errors "error code" on failure.
\remark if the data passed to this function comes from a non locked bank the outcome of this function is meaningless.
\remark the 'data' argument may come from a xlt_decrypt_locked_data() or a local xlt_read() call.
*/
XLT_LINK int XLT_API xlt_get_info_from_locked_bank(const unsigned char* data, unsigned int* pbank, unsigned int* pcounter, unsigned int* pserial, unsigned int* pgroup_number);


/**
\ingroup xlt_adv
Virginize (reset) a demo XLight device.
\param[in] device device index for the selection of a specific XLight device. This value runs from 0 to ::XLT_DEVICE_EXT_MAX -1.
\return returns ::XLT_ERROR_SUCCESS on success, an \ref xlt_Errors "error code" on failure.
\remark this function may be useful for testing allowing to completely cleanup a DEMO device, that is it doesn't work onto standard devices. 
A demo device is distinguished by standard ones by its serial number: it is set to the value '1'.
This function may be useful especially while testing xlt_bank_freeze() and xlt_bank_lock2() functions which on normal devices cannot be reverted.

\note OxySec supplies DEMO devices only for evaluation purpose and must be used only for testing on the standard devices.
*/
XLT_LINK int XLT_API xlt_virg_demo(unsigned int device);

/**
\ingroup xlt_adv
Cleanup the allocated memory by the XLight functions.
\remark in case of dll usage it is not necessary call this function, it is already called when the dll is unloaded. On the other hand it's not harmful to call it explicitly.
It is also possible call any other function after the xlt_close() is called, but in this case xlt_close() must be called again.
\note this function can't be called concurrently with any other function.
 */
XLT_LINK void XLT_API xlt_close();

/**
\ingroup xlt_adv
Initialize the environment for XLight management.
\return returns ::XLT_ERROR_SUCCESS on success, an \ref xlt_Errors "error code" on failure.

\remark It is not necessary to call this function unless the running process is using multi-threading. In this case it is necessary call this 
(or any other function accessing the device) function before starting using multi-threading.

Every XLight function communicas with the device running xlt_init() if not already done, a problem may arises the first time the communication 
environment is used if accessed simultaneously, so you must be sure that the first call is not done in concurrent access.
After the first call there is no problem in using multi-threading.
*/
XLT_LINK int XLT_API xlt_init();

/**
\ingroup xlt_adv
Perform the XLight and xNodus environment initialization to allow the reference of an xNodus device on the logical device index ::XLT_DEVICE_EXT_MAX - 1.
See \ref xnd_orig_prog for a usage example.
\param[in] addr_port a pointer to the null terminated name of the host to resolve and the port expressed as \<address\>.\<port\>
\param[in] xnodus_key_blob points to the encoding string of the xNodus RSA public key.
\param[in] user_data_blob points to the encoding string of the user data (username and private or secret key) to be used for the session open in xNodus (in this management the session is open automatically).
\param[in] user_data_wrap_key_string points to the string containing the key to unwrap the 'user_data_blob'. This parameter can be set to '0' if the 'user_data_blob' argument is not encrypted (or not present).
\return returns ::XLT_ERROR_SUCCESS on success, an \ref xnodus_errors "error code" on failure.
\remark If addr_port is set to "xnodus_local_network:15678" the device will be searched in the local network, and the used port is "15678".
*/
//\param[in] xlt_password the password of the XLight device (not necessary if the functions)
//XLT_LINK int XLT_API xnd_xlt_init(const char* addr_port, const char* xnodus_key_blob, OPT const char* user_data_blob, OPT const char* user_data_wrap_key_string, OPT const unsigned char* xlt_password);
XLT_LINK int XLT_API xnd_xlt_init(const char* addr_port, const char* xnodus_key_blob, OPT const char* user_data_blob, OPT const char* user_data_wrap_key_string);


//XLT_LINK int XLT_API xlt_storage_get_mem_size(unsigned int device, unsigned int *p_mem_size_in_blocks);

/**
\ingroup xlt_sd
Get memory size information of the memory flash in <i>XLight SD</i> devices.
\param[in] device device index for the selection of a specific XLight device. This value runs from 0 to ::XLT_DEVICE_EXT_MAX -1.
\param[out] p_mem_size_in_blocks points to an unsigned integer receiving the size in memory blocks (512 bytes) of the overall memory flash.
\param[out] p_enc_mem_size_in_blocks points to an unsigned integer receiving the size in memory blocks of the encrypted disk. If not present the return value is zero. 
\return returns ::XLT_ERROR_SUCCESS on success, an \ref xlt_Errors "error code" on failure.
\see \ref SDMEM.
*/
XLT_LINK int XLT_API xlt_storage_get_mem_size(unsigned int device, unsigned int *p_mem_size_in_blocks, unsigned int *p_enc_mem_size_in_blocks);

/**
\ingroup xlt_sd
Initialize the memory flash of an <i>XLight SD</i> device.
\param[in] device device index for the selection of a specific XLight device. This value runs from 0 to ::XLT_DEVICE_EXT_MAX -1.
\param[in] locked_mem_size_in_blocks the size in blocks of the desired size for the encrypted disk. If no encrypted disk is desired set this value to '0' (zero).
\param[in] dongle_key points to a buffer containing the <i>Dongle Key</i> set by xlt_setup() function.
\param[in] disk_password points to a buffer of length ::XLT_DISK_PASSWORD_SIZE containing the password that will be used to mount and unmount the encrypted disk.
\return returns ::XLT_ERROR_SUCCESS on success, an \ref xlt_Errors "error code" on failure.
\see \ref SDMEM.
*/
XLT_LINK int XLT_API xlt_storage_set(unsigned int device, unsigned int locked_mem_size_in_blocks, const unsigned char* dongle_key, const unsigned char* disk_password);

/**
\ingroup xlt_sd
Mount the encrypted disk of an <i>XLight SD</i> device.
\param[in] device device index for the selection of a specific XLight device. This value runs from 0 to ::XLT_DEVICE_EXT_MAX -1.
\param[in] disk_password points to a buffer of length ::XLT_DISK_PASSWORD_SIZE containing the password set by xlt_storage_set() function.
\return returns ::XLT_ERROR_SUCCESS on success, an \ref xlt_Errors "error code" on failure.
\see \ref SDMEM.
*/
XLT_LINK int XLT_API xlt_storage_unlock(unsigned int device, const unsigned char* disk_password);

/**
\ingroup xlt_sd
Mount the encrypted disk of an <i>XLight SD</i> device with read only access.
\param[in] device device index for the selection of a specific XLight device. This value runs from 0 to ::XLT_DEVICE_EXT_MAX -1.
\param[in] disk_password points to a buffer of length ::XLT_DISK_PASSWORD_SIZE containing the password set by xlt_storage_set() function.
\return returns ::XLT_ERROR_SUCCESS on success, an \ref xlt_Errors "error code" on failure.
\see \ref SDMEM.
*/
XLT_LINK int XLT_API xlt_storage_unlock_ro(unsigned int device, const unsigned char* disk_password);

/**
\ingroup xlt_sd
Unmount the encrypted disk of an <i>XLight SD</i> device.
\param[in] device device index for the selection of a specific XLight device. This value runs from 0 to ::XLT_DEVICE_EXT_MAX -1.
\param[in] disk_password points to a buffer of length ::XLT_DISK_PASSWORD_SIZE containing the password set by xlt_storage_set() function.
\return returns ::XLT_ERROR_SUCCESS on success, an \ref xlt_Errors "error code" on failure.
\see \ref SDMEM.
*/
XLT_LINK int XLT_API xlt_storage_lock(unsigned int device, const unsigned char* disk_password);



/**
\ingroup xlt_counter
Update and get the value of a counter.
See \ref TIMER_COUNTERS for an introduction to timer and counters management.
\param[in] device device index for the selection of a specific XLight device. This value runs from 0 to ::XLT_DEVICE_EXT_MAX -1.
\param[in] counter index of the counter to be used. This entry may take values from 0 to ::XLT_COUNTERS_NUM - 1.
\param[in] sub_value value to be subtracted to the indexed counter. If this value is 0 (zero) the counter value is read without modifying it.
\param[out] p_new_value point to an unsigned int value that will receive the value of the counter after the subtraction.
\return returns ::XLT_ERROR_SUCCESS on success, an \ref xlt_Errors "error code" on failure.

If sub_value is greater than the current counter value, its new value will be zero and the function returns ::XLT_ERROR_SUCCESS. This is still the case also if the counter value is already zero.

\see \ref TIMER_COUNTERS
*/
XLT_LINK int XLT_API xlt_update_get_counter(unsigned int device, unsigned int counter, unsigned int sub_value, unsigned int* p_new_value);

/**
\ingroup xlt_timer
Retrieve the current value of the timer.
See \ref TIMER_COUNTERS for an introduction to timer and counters management.
\param[in] device device index for the selection of a specific XLight device. This value runs from 0 to ::XLT_DEVICE_EXT_MAX -1.
\param[out] p_value point to an unsigned int value that will receive the current value of the timer.
\return returns ::XLT_ERROR_SUCCESS on success, an \ref xlt_Errors "error code" on failure.
\see \ref TIMER_COUNTERS
*/
XLT_LINK int XLT_API xlt_get_timer(unsigned int device, unsigned int* p_value);

/**
\ingroup xlt_counter
Generate a command buffer to a set a counter.
See \ref TIMER_COUNTERS for an introduction to timer and counters management.
\param[in] counter_cmd points to the structure ::XLT_COUNTER_CMD containing the settings to be applied to a counter.
\param[in] dongle_key points to the value of the <i>Dongle Key</i> set up by xlt_setup() function. 
\param[out] enc_cmd points to a buffer that will receive the encrypted form of the command.
\param[in] enc_cmd_size length of the buffer pointed by enc_cmd.
\param[out] p_enc_cmd_len points to an unsigned integer that will contain the number of bytes copied in enc_cmd. This entry may be set also to 0 (NULL).
\return returns ::XLT_ERROR_SUCCESS on success, an \ref xlt_Errors "error code" on failure.
\see \ref TIMER_COUNTERS
*/
XLT_LINK int XLT_API xlt_generate_counter_settings(const XLT_COUNTER_CMD* counter_cmd, const unsigned char* dongle_key, unsigned char* enc_cmd, unsigned int enc_cmd_size, unsigned int* p_enc_cmd_len);

/**
\ingroup xlt_timer
Generate a command buffer to a set the timer.
See \ref TIMER_COUNTERS for an introduction to timer and counters management.
\param[in] timer_cmd points to the structure ::XLT_TIMER_CMD containing the settings to be applied to the timer.
\param[in] dongle_key points to the value of the <i>Dongle Key</i> set up by xlt_setup() function. 
\param[out] enc_cmd points to a buffer that will receive the encrypted form of the command.
\param[in] enc_cmd_size length of the buffer pointed by enc_cmd.
\param[out] p_enc_cmd_len points to an unsigned integer that will contain the number of bytes copied in enc_cmd. This entry may be set also to 0 (NULL).
\return returns ::XLT_ERROR_SUCCESS on success, an \ref xlt_Errors "error code" on failure.
\see \ref TIMER_COUNTERS
*/
XLT_LINK int XLT_API xlt_generate_timer_settings(const XLT_TIMER_CMD* timer_cmd, const unsigned char* dongle_key, unsigned char* enc_cmd, unsigned int enc_cmd_size, unsigned int* p_enc_cmd_len);

/**
\ingroup xlt_timer
Generate a command buffer to increase the timer value.
See \ref TIMER_COUNTERS for an introduction to timer and counters management.
\param[in] timer_add_cmd points to the structure ::XLT_TIMER_ADD_CMD containing the add timer settings to be applied.
\param[in] dongle_key points to the value of the <i>Dongle Key</i> set up by xlt_setup() function.
\param[out] enc_cmd points to a buffer that will receive the encrypted form of the command.
\param[in] enc_cmd_size length of the buffer pointed by enc_cmd.
\param[out] p_enc_cmd_len points to an unsigned integer that will contain the number of bytes copied in enc_cmd. This entry may be set also to 0 (NULL).
\return returns ::XLT_ERROR_SUCCESS on success, an \ref xlt_Errors "error code" on failure.
\see \ref TIMER_COUNTERS
*/
XLT_LINK int XLT_API xlt_generate_timer_add_settings(const XLT_TIMER_ADD_CMD* timer_add_cmd, const unsigned char* dongle_key, unsigned char* enc_cmd, unsigned int enc_cmd_size, unsigned int* p_enc_cmd_len);

/**
\ingroup xlt_tc
Apply a timer or counter command onto the device.
See \ref TIMER_COUNTERS for an introduction to timer and counters management.
\param[in] device device index for the selection of a specific XLight device. This value runs from 0 to ::XLT_DEVICE_EXT_MAX -1.
\param[in] enc_cmd point to a buffer containing the encrypted command to be applied to the device.
\param[in] enc_cmd_len the length of the encrypted command.
\return returns ::XLT_ERROR_SUCCESS on success, an \ref xlt_Errors "error code" on failure.
\see \ref TIMER_COUNTERS
*/
XLT_LINK int XLT_API xlt_enc_apply_timer_counter(unsigned int device, const unsigned char* enc_cmd, unsigned int enc_cmd_len);

/**
\ingroup xlt_counter
Read in encrypted form the current state of all the counters of the device.
See \ref TIMER_COUNTERS for an introduction to timer and counters management.
\param[in] device device index for the selection of a specific XLight device. This value runs from 0 to ::XLT_DEVICE_EXT_MAX -1.
\param[out] enc_data points to a buffer that will receive the encrypted counters data retrieved from the XLight dongle.
\param[in] enc_data_size length of the buffer pointed by enc_data.
\param[out] p_enc_data_len points to an unsigned integer that will receive the number of bytes copied in enc_data. This entry may be set also to 0 (NULL).
\return returns ::XLT_ERROR_SUCCESS on success, an \ref xlt_Errors "error code" on failure.
\see \ref TIMER_COUNTERS
*/
XLT_LINK int XLT_API xlt_enc_read_counters(unsigned int device, unsigned char* enc_data, unsigned int enc_data_size, unsigned int* p_enc_data_len);

/**
\ingroup xlt_timer
Read in encrypted form the current state the device timer.
See \ref TIMER_COUNTERS for an introduction to timer and counters management.
\param[in] device device index for the selection of a specific XLight device. This value runs from 0 to ::XLT_DEVICE_EXT_MAX -1.
\param[out] enc_data points to a buffer that will receive the encrypted timer data retrieved from the XLight dongle.
\param[in] enc_data_size length of the buffer pointed by enc_data.
\param[out] p_enc_data_len points to an unsigned integer that will receive the number of bytes copied in enc_data. This entry may be set also to 0 (NULL).
\return returns ::XLT_ERROR_SUCCESS on success, an \ref xlt_Errors "error code" on failure.
\see \ref TIMER_COUNTERS
*/
XLT_LINK int XLT_API xlt_enc_read_timer(unsigned int device, unsigned char* enc_data, unsigned int enc_data_size, unsigned int* p_enc_data_len);

/**
\ingroup xlt_tc
Decrypt encrypted data from the device regarding timer or counters.
This function also extract data from encrypted commands.
See \ref TIMER_COUNTERS for an introduction to timer and counters management.
\param[in] enc_data points to encrypted data retrieved from the device or containing an encrypted command.
\param[in] enc_data_len length of the encrypted buffer.
\param[in] dongle_key points to the value of the <i>Dongle Key</i> set up by xlt_setup() function. 
\param[out] retrieved_data points to an instance of structure ::XLT_TIMER_COUNTER_INFO that will contain the decryption of the data or command passed to this function.
\return returns ::XLT_ERROR_SUCCESS on success, an \ref xlt_Errors "error code" on failure.
\see \ref TIMER_COUNTERS
*/
XLT_LINK int XLT_API xlt_timer_counters_retrieve(const unsigned char* enc_data, unsigned int enc_data_len, const unsigned char* dongle_key, XLT_TIMER_COUNTER_INFO* retrieved_data);

///////////////////////////////////////
//DATE management

/**
\ingroup xlt_date
Read in encrypted form the current state of the date license management of the device.
See \ref DATE_LICENSING for an introduction to XLight license management based on the date.
\param[in] device device index for the selection of a specific XLight device. This value runs from 0 to ::XLT_DEVICE_EXT_MAX -1.
\param[out] enc_data points to a buffer that will receive the encrypted date license data retrieved from the XLight dongle.
\param[in] enc_data_size length of the buffer pointed by enc_data.
\param[out] p_enc_data_len points to an unsigned integer that will receive the number of bytes copied in enc_data. This entry may be set also to 0 (NULL).
\return returns ::XLT_ERROR_SUCCESS on success, an \ref xlt_Errors "error code" on failure.
*/
XLT_LINK int XLT_API xlt_enc_read_date(unsigned int device, unsigned char* enc_data, unsigned int enc_data_size, unsigned int* p_enc_data_len);

/**
\ingroup xlt_date
Read the current state of the date license management of the device.
See \ref DATE_LICENSING for an introduction to XLight license management based on the date.
\param[in] device device index for the selection of a specific XLight device. This value runs from 0 to ::XLT_DEVICE_EXT_MAX -1.
\param[out] date_info points to a XLT_DATE_DATA struct that will receive the date license data of the connected device.
\return returns ::XLT_ERROR_SUCCESS on success, an \ref xlt_Errors "error code" on failure.
\note xlt_read_date() can be run by the protected application to see the current status of the license but some ::XLT_DATE_DATA entries are set always to zero and can be collected only using
remote functions. Such entries are: 
<ul>
<li>functions_to_lock_mask,
<li>device_time,
<li>cmd_counter,
<li>max_missing_update_date_error,
<li>max_missing_update_signed_date_error and 
<li>max_update_date_error. 
</ul>
*/
XLT_LINK int XLT_API xlt_read_date(unsigned int device, XLT_DATE_DATA* date_info);

/**
\ingroup xlt_date
Set the current time (date) of the device.
See \ref DATE_LICENSING for an introduction to XLight license management based on the date.
\param[in] device device index for the selection of a specific XLight device. This value runs from 0 to ::XLT_DEVICE_EXT_MAX -1.
\param[in] time the current Unix Time.
\return returns ::XLT_ERROR_SUCCESS on success, an \ref xlt_Errors "error code" on failure.
*/
XLT_LINK int XLT_API xlt_set_date(unsigned int device, unsigned int time);

/**
\ingroup xlt_date
Retrieve the challenge buffer generated by the XLight device for update signed update (\ref SIGNED_DATE_UPDATE_CONSTRAINT)
The challenge buffer need to be used for setting the signed date onto the device
See \ref DATE_LICENSING for an introduction to XLight license management based on the date.
\param[in] device device index for the selection of a specific XLight device. This value runs from 0 to ::XLT_DEVICE_EXT_MAX -1.
\param[out] enc_challenge points to a buffer that will receive an encoded form of the challenge buffer generated by the device. The length of the buffer must be not less than ::XLT_DATE_ENC_CHALLENGE_SIZE bytes long.
\param[in] enc_challenge_size length of the buffer pointed by challenge.
\param[out] p_enc_challenge_len points to an unsigned integer that will receive the length of the bytes copied in challenge. This entry may be set also to 0 (NULL).
\return returns ::XLT_ERROR_SUCCESS on success, an \ref xlt_Errors "error code" on failure.
*/
XLT_LINK int XLT_API xlt_date_get_challenge(unsigned int device, unsigned char* enc_challenge, unsigned int enc_challenge_size, unsigned int* p_enc_challenge_len);


/**
\ingroup xlt_date
Generate the license date expiration command
See \ref DATE_LICENSING for an introduction to XLight license management based on the date (and the \ref SetDateExpiration for an example of xlt_generate_date_expiration_cmd() usage).
\param[in] cmd points to the structure containing all the settings for the license expiration command.
\param[in] dongle_key points to the value of the <i>Dongle Key</i> set up by xlt_setup() function. 
\param[out] enc_cmd points to a buffer that will receive the encrypted form of the command for setting the expiration license date of an XLight device. The length of the buffer must be not less than ::XLT_DATE_ENC_EXP_CMD_SIZE bytes long.
\param[in] enc_cmd_size length of the buffer pointed by enc_cmd.
\param[out] p_enc_cmd_len points to an unsigned integer that will receive the length of the bytes copied in enc_cmd. This entry may be set also to 0 (NULL).
\return returns ::XLT_ERROR_SUCCESS on success, an \ref xlt_Errors "error code" on failure.
*/
XLT_LINK int XLT_API xlt_generate_date_expiration_cmd(const XLT_DATE_SET_EXPIRATION_CMD* cmd, const unsigned char* dongle_key, unsigned char* enc_cmd, unsigned int enc_cmd_size, unsigned int* p_enc_cmd_len);

/**
\ingroup xlt_date
Generate the signed date command.
This command uses the challenge retrieved by the XLight device using the function xlt_date_get_challenge() and decoded by xlt_date_enc_retrieve().
See \ref DATE_LICENSING for an introduction to XLight license management based on the date.
\param[in] time current Unix Time.
\param[in] challenge the challenge buffer generated by the dongle.
\param[in] challenge_len length of the challenge entry.
\param[in] dongle_key points to the value of the <i>Dongle Key</i> set up by xlt_setup() function. 
\param[out] enc_cmd points to a buffer that will receive the encrypted form of the command for the signed update of the time of the device. The length of the buffer must be not less than ::XLT_DATE_SIG_UPD_CMD_SIZE bytes long.
\param[in] enc_cmd_size length of the buffer pointed by enc_cmd.
\param[out] p_enc_cmd_len points to an unsigned integer that will receive the length of the bytes copied in enc_cmd. This entry may be set also to 0 (NULL).
\return returns ::XLT_ERROR_SUCCESS on success, an \ref xlt_Errors "error code" on failure.
\note the challenge entry is not the enc_challenge argument returned by the function xlt_date_get_challenge(), but this is the challenge buffer of the structure ::XLT_DATE_CHALLENGE returned by xlt_date_enc_retrieve().
*/
XLT_LINK int XLT_API xlt_generate_signed_date_cmd(unsigned int time, const unsigned char* challenge, unsigned int challenge_len, const unsigned char* dongle_key, unsigned char* enc_cmd, unsigned int enc_cmd_size, unsigned int* p_enc_cmd_len);

/**
\ingroup xlt_date
Apply both license expiration setting and signed date update to the XLight device.
See \ref DATE_LICENSING for an introduction to XLight license management based on the date.
\param[in] device device index for the selection of a specific XLight device. This value runs from 0 to ::XLT_DEVICE_EXT_MAX -1.
\param[in] enc_cmd point to a buffer containing the encrypted command to be applied to the device.
\param[in] enc_cmd_len the length of the encrypted command.
\return returns ::XLT_ERROR_SUCCESS on success, an \ref xlt_Errors "error code" on failure.
*/
XLT_LINK int XLT_API xlt_apply_date_enc_cmd(unsigned int device, const unsigned char* enc_cmd, unsigned int enc_cmd_len);

/**
\ingroup xlt_date
Decrypt the encrypted data returned by the device regarding the date license settings.
This function also extract data from encrypted commands for date management.
See \ref DATE_LICENSING for an introduction to XLight license management based on the date.
\param[in] enc_data points to encrypted data retrieved from the device or containing an encrypted command.
\param[in] enc_data_len length of the encrypted buffer.
\param[in] dongle_key points to the value of the <i>Dongle Key</i> set up by xlt_setup() function. 
\param[out] retrieved_data points to an instance of structure ::XLT_DATE_INFO that will contain the decryption of the data or command passed to this function.
\return returns ::XLT_ERROR_SUCCESS on success, an \ref xlt_Errors "error code" on failure.
*/
XLT_LINK int XLT_API xlt_date_enc_retrieve(const unsigned char* enc_data, unsigned int enc_data_len, const unsigned char* dongle_key, XLT_DATE_INFO* retrieved_data);

/**
\ingroup xlt_date
Date management function.
This function can take care of all the date management for the XLight device.
See \ref DATE_LICENSING for an introduction to XLight license management based on the date (and expecially the paragraph \ref AUTO_MANAGE_DATE_UPDATE).
An XLight device with date based licensing needs to be regularly accessed for setting its signed time and "normal" (non signed) time.
The non automatic functions used for such tasks are the xlt_apply_date_enc_cmd() (in conjunction with other vendor side operation) for the signed time and the xlt_set_date() for the non signed time.
xlt_date_manage() is able to completely substitute these tasks and regularly update the device also accessing internet services for getting signed update time.
\param[in] cmd one of the \ref xlt_date_manage_cmd.
\param[in] device device index for the selection of a specific XLight device. This value runs from 0 to ::XLT_DEVICE_EXT_MAX -1.
\param[in] options the options of the command specified by the cmd argument.
\param[in] args points to a string containing arguments for addressing internet URL for signed time update or NTP time service.
\param[in] label points to a buffer with length of ::XLT_LABEL_SIZE byte containing the label of the XLight device to be addressed. If this entry is set to NULL, every device is addressed.
\return returns ::XLT_ERROR_SUCCESS on success, an \ref xlt_Errors "error code" on failure.

\note the device argument is considered only when the cmd argument has values \ref ::XLT_DATE_MANAGE_DO_SET_TIME and ::XLT_DATE_MANAGE_DO_SET_TIME_ASYNC.

The entry <i>options</i> and <i>args</i> gets values with different meaning depending on the value of the cmd entry:

when <i>cmd</i> is chosen among 
<ul>
<li>::XLT_DATE_MANAGE_AUTO_START
<li>::XLT_DATE_MANAGE_DO_SET_TIME
<li>::XLT_DATE_MANAGE_DO_SET_TIME_ASYNC
</ul>

The <i>options</i> entry takes the values shown here: \ref DATE_OPT_VAL; while <i>args</i> is a string containing web addresses to reach an NTP service or the OxySec signed date service:
see \ref AUTO_MANAGE_DATE_UPDATE to see how to build it up.

When <i>cmd</i> is ::XLT_DATE_MANAGE_SET_IDLE_TIME_SEC the <i>options</i> entry represents the second of tha new idle value (that is the time elapsing from one update test cicle and the other). Usually you don't need to
use this command value. The <i>args</i> entry is ignored.

When <i>cmd</i> is ::XLT_DATE_MANAGE_MAKE_LOGS the <i>options</i> entry is considered as a boolean value: '1' starts the log management, '0' stops it (the default is no log, so you need to activate it to get the log). The <i>args</i> entry is ignored.

When <i>cmd</i> is ::XLT_DATE_MANAGE_LOG_ONLY_ERROR the <i>options</i> entry is considered as a boolean value: '1' makes the log manager to keep track only of errors, '0' makes the log manager to keep track of every event (the defalut is '0'). The <i>args</i> entry is ignored.

When <i>cmd</i> is ::XLT_DATE_MANAGE_LOG_SET_QUEUE_LEN the <i>options</i> entry is the value of the desired log buffer, that is the maximum number of the log records that can be taken. When that number is passed the older records are discarded.
The default value for this entry is 10000. The <i>args</i> entry is ignored.

For every other value of the <i>cmd</i> entry <i>options</i> and <i>args</i> are ignored.
*/
XLT_LINK int XLT_API xlt_date_manage(unsigned int cmd, unsigned int device, unsigned int options, const char* args, const unsigned char* label);

/**
\ingroup xlt_date
Retrieve the number of log records collected by the automatic date management process issued by xlt_date_manage().
See \ref DATE_LICENSING for an introduction to XLight license management based on the date.
\param[out] p_num_entries points to an unsigned integer that will receive the number of log record currently collected.
\return returns ::XLT_ERROR_SUCCESS on success, an \ref xlt_Errors "error code" on failure.
*/
XLT_LINK int XLT_API xlt_date_manage_get_num_log_records(unsigned int* p_num_entries);

/**
\ingroup xlt_date
Retrieve log records collected by the automatic date management process issued by xlt_date_manage().
See \ref DATE_LICENSING for an introduction to XLight license management based on the date.
\param[in] starting_index the index of the first record to read from the log.
\param[in] num_entries the number of entries to read from the log.
\param[out] date_log the array of XLT_DATE_LOG structure that will receive the log records. The array must contain not less then num_entries items.
\param[out] p_num_entries_retrieved points to an unsigned integer that will receive the number of entries copied into the date_log array. This entry may be set also to 0 (NULL).
\return returns ::XLT_ERROR_SUCCESS on success, an \ref xlt_Errors "error code" on failure.
*/
XLT_LINK int XLT_API xlt_date_manage_get_log_records(unsigned int starting_index, unsigned int num_entries, XLT_DATE_LOG date_log[], unsigned int* p_num_entries_retrieved);



//\cond NOT_COMMENTED
XLT_LINK int XLT_API xlt_reserved(unsigned int device, const unsigned char* direct_cmd, unsigned int direct_cmd_len,
								   unsigned char* direct_resp, unsigned int direct_resp_size);
XLT_LINK int XLT_API xlt_reserved2(const unsigned char* dongle_key, unsigned int serial, const unsigned char* oxy_pre_cmd, unsigned int oxy_pre_cmd_len, unsigned char* direct_resp, unsigned int direct_resp_size);
XLT_LINK int XLT_API xlt_xlightsd_switch_to_nondemo(unsigned int device);
//\endcond


/**
\ingroup xlt_ss
Open a session on the device (see \ref xnd_session_on_xlight).
\param[in] device device index for the selection of a specific XLight device. This value runs from 0 to ::XLT_DEVICE_EXT_MAX -1.
\param[in] password points to a buffer of length ::XLT_PASSWORD_SIZE. It contains the password to be assigned to the device.
\param[out] p_already_open points to an unsigned integer that will contain '1' if the session was already open, and '0' if not. If the pointer p_already_open is set to zero the argument is ignored.
\return returns ::XLT_ERROR_SUCCESS on success, an \ref xlt_Errors "error code" on failure.
\remark if the device referenced is xNodus the argument p_already_open is always ignored.
*/
XLT_LINK int XLT_API xlt_open_session(unsigned int device, const unsigned char* password, unsigned int* p_already_open);

/**
\ingroup xlt_ss
Close a session on the device (see \ref xnd_session_on_xlight).
\param[in] device device index for the selection of a specific XLight device. This value runs from 0 to ::XLT_DEVICE_EXT_MAX -1.
\return returns ::XLT_ERROR_SUCCESS on success, an \ref xlt_Errors "error code" on failure.
*/
XLT_LINK int XLT_API xlt_close_session(unsigned int device);


#ifdef __cplusplus
}
#endif

#endif