From dce4142f502d007175a564d937e04a909e3463fd Mon Sep 17 00:00:00 2001 From: Dario Sassi Date: Tue, 2 Jan 2018 14:25:25 +0000 Subject: [PATCH] OxySec : - nuova libreria per gestire anche xNodus oltre a xLight. --- OxySec/Include/xlt.h | 799 ++++--- OxySec/Include/xnd.h | 4055 +++++++++++++++++++++++++++++++++++ OxySec/Lib/x32/oxyxlt.obj | Bin 259056 -> 0 bytes OxySec/Lib/x32/xnodus32.obj | Bin 0 -> 667665 bytes OxySec/Lib/x64/oxyxlt.obj | Bin 471589 -> 0 bytes OxySec/Lib/x64/xnodus.obj | Bin 0 -> 1320922 bytes 6 files changed, 4589 insertions(+), 265 deletions(-) create mode 100644 OxySec/Include/xnd.h delete mode 100644 OxySec/Lib/x32/oxyxlt.obj create mode 100644 OxySec/Lib/x32/xnodus32.obj delete mode 100644 OxySec/Lib/x64/oxyxlt.obj create mode 100644 OxySec/Lib/x64/xnodus.obj diff --git a/OxySec/Include/xlt.h b/OxySec/Include/xlt.h index 26d8367..b78772e 100644 --- a/OxySec/Include/xlt.h +++ b/OxySec/Include/xlt.h @@ -1,18 +1,27 @@ -/** \file - * XLight Library. - * \mainpage XLight Library Documentation +/** +\file +\page xlt_library XLight Library Documentation + * + * + +// \note +> This is the reference manual for the XLight APIs.
+> Before reading this document it is strongly recommended to see the following documentation: +> +> To access these links it is necessary that OxySec has enabled a Google account of yours with due permissions. Ask OxySec what to do if you haven't such permission. + + +
+\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".

-This is the documentation of the \ref xltapi "APIs" for the communication between the host computer and the XLight device. +This is the documentation of the \ref xltapi_old "APIs" for the communication between the host computer and the XLight device. -At present XLight offers API only for Windows operating system. -No driver installation is needed. +This documentation is extracted from the original XLight documentation, now it is part of the \ref xnd_mainpage "xNodus project". -

The libraries are supplied in dll and obj format. -- Dlls (oxyxlt.dll, 32 and 64 bit) are usable by any application which can be interfaced with DLLs. -- OBJs (oxyxlt.obj, 32 and 64 bit) can be integrated into "Microsoft Visual Studio 2008" C, C++ projects. -

-The interfaces supplied by the libraries (both dll and obj) are declered inside the file xlt.h and this documentation describes such interfaces.

@@ -22,16 +31,93 @@ Read the following topics on Advanced XLight protection

*/ +/** \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: +
    +
  1. xlt_close() is not thread safe. +
  2. 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. +
  3. 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. +
+ +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 @@ -45,27 +131,40 @@ Read the following topics on Advanced XLight protection /** 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 -/** \name Compiler +/** \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 //@} -/** \defgroup constants Constants -Constants used by the \ref xltapi functions. -@{ -*/ +//\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). @@ -89,19 +188,21 @@ Constants used by the \ref xltapi functions. #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 Models +/** \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 Sizes +/** \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. @{ */ @@ -113,9 +214,14 @@ Constants used by the \ref xltapi functions. #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 devices. Useful when scanning all the device with the xlt_getinfo() functions. +#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 @@ -131,16 +237,17 @@ Constants used by the \ref xltapi functions. #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 +#define XLT_COUNTERS_NUM 4 ///< number of usable counters in XLight +//@} // Sizes -//@} -/** \defgroup Errors Errors +/** \defgroup xlt_Errors Errors Code + * \ingroup xlt_defines * Error codes. * The XLight functions return the following error codes. @{ */ -#define XLT_ERROR_SUCCESS 0 ///< No error. +#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. @@ -171,11 +278,6 @@ Constants used by the \ref xltapi functions. #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) -/* __ * \defgroup DateThreadErrors Errors of date management functions -* Error codes. -* The XLight functions return the following error codes. - @ __ { - */ #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 ///idle_time_minutes 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{ @@ -236,38 +356,47 @@ struct _XLT_TIMER_ADD_CMD{ 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 -The structure contains the data of a XLight counter. +\ingroup xlt_tc_struct +The structure contains the data of an XLight counter. */ struct _XLT_COUNTER_DATA{ - XLT_ULONG_LONG trigger_functions_mask;///< list of functions that causes the counter to be decremented - XLT_ULONG_LONG functions_to_lock_mask;///< functions that won't work after counter expiration (reached 0) + 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 -Contains the command for setting a counter. +\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. */ @@ -278,18 +407,32 @@ union _XLT_TC_INFO{ 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 -a XLight device or from an encrypted command to be sent to the device +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. @{ */ @@ -299,23 +442,25 @@ These are the value types associated to the data contained int the structure XLT #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()) -//@} -/** Timer and counters info retrieved from a 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_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'). @{ */ @@ -367,9 +512,10 @@ typedef struct _XLT_TIMER_COUNTER_INFO{ #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. @{ */ @@ -422,8 +568,9 @@ typedef struct _XLT_TIMER_COUNTER_INFO{ #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. @@ -443,25 +590,21 @@ Define for triggering all the triggerable functions. */ #define XLT_TRIGGER_ALL (XLT_LOCK_ALL | XLT_TRIGGER_GET_INFO) -//@} -/** \defgroup date Date structures -Data structures and defines for the management of the XLight time based license management. -@{ -*/ +// =============================================================================== //\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). + 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) . @@ -477,49 +620,57 @@ struct _XLT_DATE_DATA{ 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 a XLight device for managing the license based on date expiration. +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). + 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). @@ -531,25 +682,30 @@ struct _XLT_DATE_SET_EXPIRATION_CMD{ 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. */ @@ -559,15 +715,18 @@ union _XLT_D_INFO{ XLT_DATE_DATA date_data; ///< XLT_DATE_DATA type: date information data. XLT_DATE_CHALLENGE date_challenge; ///
  • ::XLT_DATE_MANAGE_AUTO_START @@ -637,6 +800,7 @@ These values can be used together as bitmask. //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()). @{ */ @@ -651,13 +815,14 @@ an event or an error occurred #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 Errors) + 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; @@ -665,56 +830,77 @@ typedef struct _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 support the Lock2 feature on basic XLight devices. -#define RSA_AVAILABLE_MIN_VERSION_ON_MODEL_BASIC_USBHID 0x200 ///< minimum XLight version that support the RSA feature on basic XLight devices. -#define SESSION_KEY_AVAILABLE_MIN_VERSION_ON_MODEL_BASIC_USBHID 0x200 ///< minimum XLight version that support the AES Session Key feature on basic XLight devices. -#define SD_MEM_AVAILABLE_MIN_VERSION_ON_MODEL_BASIC_USBHID 0xffff ///< minimum XLight version that support the SD memory 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 support timer and counter management on basic XLight devices. -#define DATE_AVAILABLE_MIN_VERSION_ON_MODEL_BASIC_USBHID 0x220 ///< minimum XLight version that support timer and counter management on basic XLight devices. +#define LOCK2_AVAILABLE_MIN_VERSION_ON_MODEL_BASIC_USBHID 0x101 ///< minimum XLight version that supports the Lock2 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 AES Session Key feature on basic XLight devices. +#define SD_MEM_AVAILABLE_MIN_VERSION_ON_MODEL_BASIC_USBHID 0xffff ///< minimum XLight version that supports the SD memory 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 session management on basic XLight devices. +#define RSA_BOUND_TO_SN_MIN_VERSION_ON_MODEL_BASIC_USBHID 0x240 ///< minimum XLight version that supports Rsa bound to serial management on basic XLight devices. +#define TRAP_MIN_VERSION_ON_MODEL_BASIC_USBHID 0x240 ///< minimum XLight version that supports trap 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 support the Lock2 feature on XLight SD devices. -#define RSA_AVAILABLE_MIN_VERSION_ON_MODEL_USBHID_SD 0x100 ///< minimum XLight version that support the RSA feature on XLight SD devices. -#define SESSION_KEY_AVAILABLE_MIN_VERSION_ON_MODEL_USBHID_SD 0x100 ///< minimum XLight version that support the AES Session Key feature on XLight SD devices. -#define SD_MEM_AVAILABLE_MIN_VERSION_ON_MODEL_USBHID_SD 0x100 ///< minimum XLight version that support the SD memory feature on XLight SD devices. +#define LOCK2_AVAILABLE_MIN_VERSION_ON_MODEL_USBHID_SD 0x100 ///< minimum XLight version that supports the Lock2 feature on XLight SD devices. +#define RSA_AVAILABLE_MIN_VERSION_ON_MODEL_USBHID_SD 0x100 ///< minimum XLight version that supports the RSA feature on XLight SD devices. +#define SESSION_KEY_AVAILABLE_MIN_VERSION_ON_MODEL_USBHID_SD 0x100 ///< minimum XLight version that supports the AES Session Key feature on XLight SD devices. +#define SD_MEM_AVAILABLE_MIN_VERSION_ON_MODEL_USBHID_SD 0x100 ///< minimum XLight version that supports the SD memory feature on XLight SD devices. +#define TIMER_AVAILABLE_MIN_VERSION_ON_MODEL_USBHID_SD 0xffff ///< minimum XLight version that supports timer and counter management on XLight SD devices. +#define DATE_AVAILABLE_MIN_VERSION_ON_MODEL_USBHID_SD 0xffff ///< minimum XLight version that supports timer and counter management on XLight SD devices. +#define SESSION_AVAILABLE_MIN_VERSION_ON_MODEL_USBHID_SD 0x105 ///< minimum XLight version that supports session management on XLight SD devices. +#define RSA_BOUND_TO_SN_MIN_VERSION_ON_MODEL_USBHID_SD 0xffff ///< minimum XLight version that supports Rsa bound to serial management on XLight SD devices. +#define TRAP_MIN_VERSION_ON_MODEL_USBHID_SD 0xffff ///< minimum XLight version that supports trap management on XLight SD 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 XLight SD devices. -#define TIMER_AVAILABLE_MIN_VERSION_ON_MODEL_USBHID_SD 0xffff ///< minimum XLight version that support timer and counter management on XLight SD devices. -#define DATE_AVAILABLE_MIN_VERSION_ON_MODEL_USBHID_SD 0xffff ///< minimum XLight version that support timer and counter management on XLight SD devices. +//@} //releases_feature -//@} - -//@} //constants - -/** \defgroup xltapi XLight Api -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: -
      -
    1. xlt_close() is not thread safe. -
    2. 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. -
    3. 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. -
    - -The APIs can be used simultaneously also by different processes communicating with the same device and the consideration '3' above holds as well. - - @{ -*/ /** + * \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_MAX -1. + * \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 pversion is NULL this parameter is ignored. * \param[out] pmodel points to an unsigned int where the device model identification code must be returned. If pmodel 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 pflags 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 pserial is NULL this parameter is ignored. * \param[out] label points to the memory location where the label of the device must be returned. If label is NULL this parameter is ignored. - \return returns ::XLT_ERROR_SUCCESS on success, an \ref Errors "error code" on failure. + \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 @@ -733,14 +919,14 @@ The APIs can be used simultaneously also by different processes communicating wi int i; unsigned int device; - for(device = 0; device < XLT_DEVICE_MAX; 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", device); + 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"); @@ -767,25 +953,26 @@ XLT_LINK int XLT_API xlt_getinfo(unsigned int device, unsigned int* pversion, un /** + * \ingroup xlt_adv Set the label, the password and the cryptographic keys of the device.

    Warning! This function can be executed only once! All the subsequent calls will fail. \note this function produces an irreversible setting onto the XLight device, hence use it very carefully.

    - \param[in] device device index for the selection of a specific XLight device. This value runs from 0 to ::XLT_DEVICE_MAX -1. + \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 Dongle Key: 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 (Challenge Key) that will be used by the functions xlt_challenge(). - \return returns ::XLT_ERROR_SUCCESS on success, an \ref Errors "error code" on failure. + \return returns ::XLT_ERROR_SUCCESS on success, an \ref xlt_Errors "error code" on failure. \remark password, dongle_key (the Dongle Key) and cr_key (the Challenge Response Key or shortly Challenge Key) 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 password, Dongle Key and Challenge Key are optional, it is strongly recommended to set them with non trivial values to forbid memory access (using password) to unauthorized application, and to allow the protected application to make sure of the presence of the XLight device (using Challenge Key) 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() work. + \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 Dongle Key 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 XLight device also in its more advanced feaures. @@ -826,41 +1013,13 @@ XLT_LINK int XLT_API xlt_setup(unsigned int device, const unsigned char* label, /** - * 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); - - -/** -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_MAX -1. + * \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 Errors "error code" on failure. + \return returns ::XLT_ERROR_SUCCESS on success, an \ref xlt_Errors "error code" on failure. \remark the password 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 @@ -876,8 +1035,8 @@ Write into a memory bank of the XLight device. strcpy((char*)data, "Some data"); memset(data + strlen("Some data"), 0x00, sizeof(data) - strlen("Some data")); - strcpy((char*)password, "My password"); - memset(password + strlen("My password"), 0x00, sizeof(password) - strlen("My password")); + 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); @@ -891,12 +1050,13 @@ XLT_LINK int XLT_API xlt_write(unsigned int device, const unsigned char* passwor /** -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_MAX -1. + * \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 Errors "error code" on failure. + \return returns ::XLT_ERROR_SUCCESS on success, an \ref xlt_Errors "error code" on failure. \remark the password 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 @@ -907,8 +1067,8 @@ Read from a memory bank of the XLight device. unsigned char password[XLT_PASSWORD_SIZE]; unsigned char data[XLT_BANK_SIZE]; - strcpy((char*)password, "My password"); - memset(password + strlen("My password"), 0x00, sizeof(password) - strlen("My password")); + 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); @@ -927,14 +1087,15 @@ XLT_LINK int XLT_API xlt_read(unsigned int device, const unsigned char* password /** + * \ingroup xlt_bank Freeze a given memory bank. After freezing it won't be possible write inside the given bank any longer. \note this function produces an irreversible setting onto the XLight device, hence use it very carefully. - \param[in] device device index for the selection of a specific XLight device. This value runs from 0 to ::XLT_DEVICE_MAX -1. + \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 Errors "error code" on failure. + \return returns ::XLT_ERROR_SUCCESS on success, an \ref xlt_Errors "error code" on failure. \remark the password 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 @@ -944,10 +1105,10 @@ Freeze a given memory bank. After freezing it won't be possible write inside the unsigned int device = 0; unsigned char password[XLT_PASSWORD_SIZE]; - strcpy((char*)password, "My password"); - memset(password + strlen("My password"), 0x00, sizeof(password) - strlen("My password")); + strcpy((char*)password, "My XLight password"); + memset(password + strlen("My XLight password"), 0x00, sizeof(password) - strlen("My XLight password")); - //freeze the bank 0 of a XLight dongle + //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){ @@ -961,11 +1122,12 @@ XLT_LINK int XLT_API xlt_bank_freeze(unsigned int device, const unsigned char* p /** +\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_MAX -1. + \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 Errors "error code" on failure. + \return returns ::XLT_ERROR_SUCCESS on success, an \ref xlt_Errors "error code" on failure. \note the encryption function uses as cryptographic key the Dongle Key entry set by xlt_setup(). \note We strongly recommend never to put Dongle Key in the protected application. Use Dongle Key to encrypt data, but not for authentication process like discussed in xlt_challenge() documentation. @@ -1028,11 +1190,12 @@ XLT_LINK int XLT_API xlt_encrypt(unsigned int device, const unsigned char* plain /** +\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_MAX -1. + \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 Errors "error code" on failure. + \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 Dongle Key entry set by xlt_setup(). @@ -1059,12 +1222,13 @@ XLT_LINK int XLT_API xlt_decrypt(unsigned int device, const unsigned char* ciphe /** +\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_MAX -1. + \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 Errors "error code" on failure. + \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 cr_key (Challenge Response Key) 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 @@ -1140,13 +1304,14 @@ The protected software send a value and check that the outcome is as expected. XLT_LINK int XLT_API xlt_challenge(unsigned int device, const unsigned char* challenge, unsigned char* response); /** -Load on a XLight device the session AES key to be used for AES session encryption functions. + * \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 Session Key protection. - \param[in] device device index for the selection of a specific XLight device. This value runs from 0 to ::XLT_DEVICE_MAX -1. + \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 Session Key encrypted with Dongle Key. - \return returns ::XLT_ERROR_SUCCESS on success, an \ref Errors "error code" on failure. + \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 Dongle Key. In oreder to produce the wrapped form of the Session Key use xlt_session_wrap_key(). @@ -1162,13 +1327,14 @@ See \ref Session_KeyProtection "here" for a source code example using this funct 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 Session Key. See \ref AES_Session_Key for an introduction on Session Key protection. - \param[in] device device index for the selection of a specific XLight device. This value runs from 0 to ::XLT_DEVICE_MAX -1. + \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 Errors "error code" on failure. + \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 Session Keys specified by the index key_index, and the corrisponding key was previously set by the xlt_session_decrypt() function. @@ -1180,13 +1346,14 @@ See \ref AES_Session_Key for an introduction on Session Key protection. 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 Session Key. See \ref AES_Session_Key for an introduction on Session Key protection. - \param[in] device device index for the selection of a specific XLight device. This value runs from 0 to ::XLT_DEVICE_MAX -1. + \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 Errors "error code" on failure. + \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(). @@ -1196,12 +1363,13 @@ See \ref AES_Session_Key for an introduction on Session Key protection. 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 Session Key. See \ref AES_Session_Key for an introduction on Session Key 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 Dongle Key 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 Errors "error code" on failure. +\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 Dongle Key into the protected software. This is an utility software to compute the wrapped version of a Session Key and must be done in an utility software not distributed to the @@ -1216,6 +1384,7 @@ See \ref Session_KeyPreliminary "here" for a source code example using this func 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. @@ -1226,7 +1395,7 @@ See \ref RSA_Protection for an introduction on the RSA protection in XLight. 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 Errors "error code" on failure. +\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. @@ -1237,14 +1406,15 @@ XLT_LINK int XLT_API xlt_rsa_generate_key(unsigned int bit_size, unsigned char* 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 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 Dongle Key. \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 Wrapped Key pointed by wrapped_key. The length of a Wrapped Key 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 Errors "error code" on failure. +\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 Wrapped Key may reside into a protected software or exposed to the public access without revealing its real content. @@ -1256,14 +1426,37 @@ In order to insert a private key onto the device the Wrapped Key must be 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 Dongle Key. +\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 Wrapped Key pointed by wrapped_key. The length of a Wrapped Key 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 Wrapped Key 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 Wrapped Key must be passed to the function xlt_rsa_set_privkey(). + +

    Supported version: 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_MAX -1. +\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 Wrapped Key data. -\return ::XLT_ERROR_SUCCESS on success, an \ref Errors "error code" on failure. +\return ::XLT_ERROR_SUCCESS on success, an \ref xlt_Errors "error code" on failure. -\note on a 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 +\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(). @@ -1276,6 +1469,7 @@ nevertheless it can be always overwritten with a new one. 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 @@ -1287,13 +1481,14 @@ See \ref RSA_Protection for an introduction on the RSA protection in XLight. 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 Errors "error code" on failure. +\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.

    Supported version: 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 @@ -1305,21 +1500,22 @@ See \ref RSA_Protection for an introduction on the RSA protection in XLight. 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 Errors "error code" on failure. +\return ::XLT_ERROR_SUCCESS on success, an \ref xlt_Errors "error code" on failure.

    Supported version: 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_MAX -1. +\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 Errors "error code" on failure. +\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.

    Supported version: this function is available on XLight devices version 2.0 or later. @@ -1327,16 +1523,17 @@ if the length is ::XLT_RSA_512_PLAINTEXT_SIZE the 512-bit key is used, for any o 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 this function produces an irreversible setting onto the XLight device, hence use it very carefully. 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_MAX -1. +\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 Errors "error code" on failure. +\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(). @@ -1355,16 +1552,17 @@ The remaining bytes are used by the locking mechanism management. 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 (Lock2). \note this function produces an irreversible setting onto the XLight device, hence use it very carefully. 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_MAX -1. +\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 Errors "error code" on failure. +\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(). @@ -1383,27 +1581,29 @@ The remaining bytes are used by the locking mechanism management. 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 Lock2 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_MAX -1. +\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 Errors "error code" on failure. +\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 Lock2 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_MAX -1. +\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 Errors "error code" on failure. +\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 password, but its outcome can't be used as is, because it needs decryption. @@ -1416,6 +1616,7 @@ XLT_LINK int XLT_API xlt_read_locked(unsigned int device, unsigned int bank, uns /** +\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()). @@ -1428,7 +1629,7 @@ See \ref locked_memory. \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 data into a locked bank. -\return returns ::XLT_ERROR_SUCCESS on success, an \ref Errors "error code" on failure. +\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. @@ -1440,6 +1641,7 @@ this remote update technique can be used, for instance, for license management p 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 Lock2 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()). @@ -1452,7 +1654,7 @@ See \ref locked_memory. \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 data into a locked bank. -\return returns ::XLT_ERROR_SUCCESS on success, an \ref Errors "error code" on failure. +\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. @@ -1465,6 +1667,7 @@ this remote update technique can be used, for instance, for license management p 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()). @@ -1476,7 +1679,7 @@ See \ref locked_memory. \param[in] dongle_key points to a buffer of length ::XLT_KEY_SIZE. It contains the AES-256 key Dongle Key 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 Errors "error code" on failure. +\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. @@ -1485,6 +1688,7 @@ For further notices see the comments of xlt_set_write_locked_serial_check(), the 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 Lock2 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()). @@ -1496,7 +1700,7 @@ See \ref locked_memory. \param[in] dongle_key points to a buffer of length ::XLT_KEY_SIZE. It contains the AES-256 key Dongle Key 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 Errors "error code" on failure. +\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. @@ -1506,13 +1710,14 @@ For further notices see the comments of xlt_set_write_locked_serial_check(), the 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 Errors "error code" on failure. +\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 @@ -1528,13 +1733,14 @@ These bytes convey information that may be retrieved using xlt_get_info_from_loc 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 Lock2 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 Errors "error code" on failure. +\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 @@ -1551,6 +1757,7 @@ These bytes convey information that may be retrieved using xlt_get_info_from_loc 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 Lock2 mode). See \ref locked_memory. @@ -1559,7 +1766,7 @@ See \ref locked_memory. \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 Errors "error code" on failure. +\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. */ @@ -1567,9 +1774,10 @@ XLT_LINK int XLT_API xlt_get_info_from_locked_bank(const unsigned char* data, un /** +\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_MAX -1. -\return returns ::XLT_ERROR_SUCCESS on success, an \ref Errors "error code" on failure. +\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. @@ -1579,6 +1787,7 @@ This function may be useful especially while testing xlt_bank_freeze() and xlt_b 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. @@ -1587,8 +1796,9 @@ It is also possible call any other function after the xlt_close() is called, but 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 Errors "error code" on failure. +\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. @@ -1599,52 +1809,73 @@ 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 \.\ +\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 XLight SD devices. -\param[in] device device index for the selection of a specific XLight device. This value runs from 0 to ::XLT_DEVICE_MAX -1. +\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 Errors "error code" on failure. +\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 XLight SD device. -\param[in] device device index for the selection of a specific XLight device. This value runs from 0 to ::XLT_DEVICE_MAX -1. +\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 Dongle Key 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 Errors "error code" on failure. +\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 XLight SD device. -\param[in] device device index for the selection of a specific XLight device. This value runs from 0 to ::XLT_DEVICE_MAX -1. +\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 Errors "error code" on failure. +\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 XLight SD 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_MAX -1. +\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 Errors "error code" on failure. +\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 XLight SD device. -\param[in] device device index for the selection of a specific XLight device. This value runs from 0 to ::XLT_DEVICE_MAX -1. +\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 Errors "error code" on failure. +\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); @@ -1652,13 +1883,14 @@ XLT_LINK int XLT_API xlt_storage_lock(unsigned int device, const unsigned char* /** +\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_MAX -1. +\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 Errors "error code" on failure. +\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. @@ -1667,16 +1899,18 @@ If sub_value is greater than the current counter value, its new value will be ze 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_MAX -1. +\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 Errors "error code" on failure. +\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. @@ -1684,12 +1918,13 @@ See \ref TIMER_COUNTERS for an introduction to timer and counters management. \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 Errors "error code" on failure. +\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. @@ -1697,12 +1932,13 @@ See \ref TIMER_COUNTERS for an introduction to timer and counters management. \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 Errors "error code" on failure. +\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. @@ -1710,47 +1946,51 @@ See \ref TIMER_COUNTERS for an introduction to timer and counters management. \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 Errors "error code" on failure. +\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_MAX -1. +\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 Errors "error code" on failure. +\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_MAX -1. +\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 Errors "error code" on failure. +\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_MAX -1. +\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 Errors "error code" on failure. +\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. @@ -1758,7 +1998,7 @@ See \ref TIMER_COUNTERS for an introduction to timer and counters management. \param[in] enc_data_len length of the encrypted buffer. \param[in] dongle_key points to the value of the Dongle Key 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 Errors "error code" on failure. +\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); @@ -1767,22 +2007,24 @@ XLT_LINK int XLT_API xlt_timer_counters_retrieve(const unsigned char* enc_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_MAX -1. +\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 Errors "error code" on failure. +\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_MAX -1. +\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 Errors "error code" on failure. +\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: