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:

      @@ -1797,67 +2039,72 @@ remote functions. Such entries are: XLT_LINK int XLT_API xlt_read_date(unsigned int device, XLT_DATE_DATA* date_info); /** +\ingroup xlt_date Set the current time (date) of the device. See \ref DATE_LICENSING for an introduction to XLight license management based on the date. -\param[in] device device index for the selection of a specific XLight device. This value runs from 0 to ::XLT_DEVICE_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] time the current Unix Time. -\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_set_date(unsigned int device, unsigned int time); /** +\ingroup xlt_date Retrieve the challenge buffer generated by the XLight device for update signed update (\ref SIGNED_DATE_UPDATE_CONSTRAINT) The challenge buffer need to be used for setting the signed date onto the device See \ref DATE_LICENSING for an introduction to XLight license management based on the date. -\param[in] device device index for the selection of a specific XLight device. This value runs from 0 to ::XLT_DEVICE_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_challenge points to a buffer that will receive an encoded form of the challenge buffer generated by the device. The length of the buffer must be not less than ::XLT_DATE_ENC_CHALLENGE_SIZE bytes long. \param[in] enc_challenge_size length of the buffer pointed by challenge. \param[out] p_enc_challenge_len points to an unsigned integer that will receive the length of the bytes copied in challenge. This entry may be set also to 0 (NULL). -\return returns ::XLT_ERROR_SUCCESS on success, an \ref 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_date_get_challenge(unsigned int device, unsigned char* enc_challenge, unsigned int enc_challenge_size, unsigned int* p_enc_challenge_len); /** +\ingroup xlt_date Generate the license date expiration command See \ref DATE_LICENSING for an introduction to XLight license management based on the date (and the \ref SetDateExpiration for an example of xlt_generate_date_expiration_cmd() usage). -\param[in] cmd points to the structure containing all the settings for the license expiration command +\param[in] cmd points to the structure containing all the settings for the license expiration command. \param[in] dongle_key points to the value of the Dongle Key set up by xlt_setup() function. -\param[out] enc_cmd points to a buffer that will receive the encrypted form of the command for setting the expiration license date of a Xlight device. The length of the buffer must be not less than ::XLT_DATE_ENC_EXP_CMD_SIZE bytes long. +\param[out] enc_cmd points to a buffer that will receive the encrypted form of the command for setting the expiration license date of an XLight device. The length of the buffer must be not less than ::XLT_DATE_ENC_EXP_CMD_SIZE bytes long. \param[in] enc_cmd_size length of the buffer pointed by enc_cmd. \param[out] p_enc_cmd_len points to an unsigned integer that will receive the length of the bytes copied in enc_cmd. This entry may be set also to 0 (NULL). -\return returns ::XLT_ERROR_SUCCESS on success, an \ref 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_generate_date_expiration_cmd(const XLT_DATE_SET_EXPIRATION_CMD* cmd, const unsigned char* dongle_key, unsigned char* enc_cmd, unsigned int enc_cmd_size, unsigned int* p_enc_cmd_len); /** +\ingroup xlt_date Generate the signed date command. This command uses the challenge retrieved by the XLight device using the function xlt_date_get_challenge() and decoded by xlt_date_enc_retrieve(). See \ref DATE_LICENSING for an introduction to XLight license management based on the date. \param[in] time current Unix Time. -\param[in] challenge the challenge buffer generated by the dongle -\param[in] challenge_len length of the challenge entry +\param[in] challenge the challenge buffer generated by the dongle. +\param[in] challenge_len length of the challenge entry. \param[in] dongle_key points to the value of the Dongle Key set up by xlt_setup() function. \param[out] enc_cmd points to a buffer that will receive the encrypted form of the command for the signed update of the time of the device. The length of the buffer must be not less than ::XLT_DATE_SIG_UPD_CMD_SIZE bytes long. \param[in] enc_cmd_size length of the buffer pointed by enc_cmd. \param[out] p_enc_cmd_len points to an unsigned integer that will receive the length of the bytes copied in enc_cmd. This entry may be set also to 0 (NULL). -\return returns ::XLT_ERROR_SUCCESS on success, an \ref Errors "error code" on failure. +\return returns ::XLT_ERROR_SUCCESS on success, an \ref xlt_Errors "error code" on failure. \note the challenge entry is not the enc_challenge argument returned by the function xlt_date_get_challenge(), but this is the challenge buffer of the structure ::XLT_DATE_CHALLENGE returned by xlt_date_enc_retrieve(). */ XLT_LINK int XLT_API xlt_generate_signed_date_cmd(unsigned int time, const unsigned char* challenge, unsigned int challenge_len, const unsigned char* dongle_key, unsigned char* enc_cmd, unsigned int enc_cmd_size, unsigned int* p_enc_cmd_len); - /** +\ingroup xlt_date Apply both license expiration setting and signed date update to the XLight device. See \ref DATE_LICENSING for an introduction to XLight license management based on the date. -\param[in] device device index for the selection of a specific XLight device. This value runs from 0 to ::XLT_DEVICE_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. */ XLT_LINK int XLT_API xlt_apply_date_enc_cmd(unsigned int device, const unsigned char* enc_cmd, unsigned int enc_cmd_len); /** +\ingroup xlt_date Decrypt the encrypted data returned by the device regarding the date license settings. This function also extract data from encrypted commands for date management. See \ref DATE_LICENSING for an introduction to XLight license management based on the date. @@ -1865,23 +2112,24 @@ See \ref DATE_LICENSING for an introduction to XLight license management based o \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_DATE_INFO that will contain the decryption of the data or command passed to this function. -\return returns ::XLT_ERROR_SUCCESS on success, an \ref 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_date_enc_retrieve(const unsigned char* enc_data, unsigned int enc_data_len, const unsigned char* dongle_key, XLT_DATE_INFO* retrieved_data); /** +\ingroup xlt_date Date management function. This function can take care of all the date management for the XLight device. See \ref DATE_LICENSING for an introduction to XLight license management based on the date (and expecially the paragraph \ref AUTO_MANAGE_DATE_UPDATE). -A XLight device with date based licensing needs to be regularly accessed for setting its signed time and "normal" (non signed) time. +An XLight device with date based licensing needs to be regularly accessed for setting its signed time and "normal" (non signed) time. The non automatic functions used for such tasks are the xlt_apply_date_enc_cmd() (in conjunction with other vendor side operation) for the signed time and the xlt_set_date() for the non signed time. xlt_date_manage() is able to completely substitute these tasks and regularly update the device also accessing internet services for getting signed update time. -\param[in] cmd one of the \ref xlt_date_manage_cmd -\param[in] device device index for the selection of a specific XLight device. This value runs from 0 to ::XLT_DEVICE_MAX -1. -\param[in] options the options of the command specified by the cmd argument -\param[in] args points to a string containing arguments for addressing internet URL for signed time update or NTP time service -\param[in] label points to a buffer with length of ::XLT_LABEL_SIZE byte containing the label of the XLight device to be addressed. If this entry is set to NULL, every device is addressed -\return returns ::XLT_ERROR_SUCCESS on success, an \ref Errors "error code" on failure. +\param[in] cmd one of the \ref xlt_date_manage_cmd. +\param[in] device device index for the selection of a specific XLight device. This value runs from 0 to ::XLT_DEVICE_EXT_MAX -1. +\param[in] options the options of the command specified by the cmd argument. +\param[in] args points to a string containing arguments for addressing internet URL for signed time update or NTP time service. +\param[in] label points to a buffer with length of ::XLT_LABEL_SIZE byte containing the label of the XLight device to be addressed. If this entry is set to NULL, every device is addressed. +\return returns ::XLT_ERROR_SUCCESS on success, an \ref xlt_Errors "error code" on failure. \note the device argument is considered only when the cmd argument has values \ref ::XLT_DATE_MANAGE_DO_SET_TIME and ::XLT_DATE_MANAGE_DO_SET_TIME_ASYNC. @@ -1912,21 +2160,23 @@ For every other value of the cmd entry options and args are XLT_LINK int XLT_API xlt_date_manage(unsigned int cmd, unsigned int device, unsigned int options, const char* args, const unsigned char* label); /** +\ingroup xlt_date Retrieve the number of log records collected by the automatic date management process issued by xlt_date_manage(). See \ref DATE_LICENSING for an introduction to XLight license management based on the date. \param[out] p_num_entries points to an unsigned integer that will receive the number of log record currently collected. -\return returns ::XLT_ERROR_SUCCESS on success, an \ref 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_date_manage_get_num_log_records(unsigned int* p_num_entries); /** +\ingroup xlt_date Retrieve log records collected by the automatic date management process issued by xlt_date_manage(). See \ref DATE_LICENSING for an introduction to XLight license management based on the date. -\param[in] starting_index the index of the first record to read from the log -\param[in] num_entries the number of entries to read from the log -\param[out] date_log the array of XLT_DATE_LOG structure that will receive the log records. The array must contain not less then num_entries items +\param[in] starting_index the index of the first record to read from the log. +\param[in] num_entries the number of entries to read from the log. +\param[out] date_log the array of XLT_DATE_LOG structure that will receive the log records. The array must contain not less then num_entries items. \param[out] p_num_entries_retrieved points to an unsigned integer that will receive the number of entries copied into the date_log array. This entry may be set also to 0 (NULL). -\return returns ::XLT_ERROR_SUCCESS on success, an \ref 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_date_manage_get_log_records(unsigned int starting_index, unsigned int num_entries, XLT_DATE_LOG date_log[], unsigned int* p_num_entries_retrieved); @@ -1935,11 +2185,29 @@ XLT_LINK int XLT_API xlt_date_manage_get_log_records(unsigned int starting_index //\cond NOT_COMMENTED XLT_LINK int XLT_API xlt_reserved(unsigned int device, const unsigned char* direct_cmd, unsigned int direct_cmd_len, unsigned char* direct_resp, unsigned int direct_resp_size); -XLT_LINK int xlt_reserved2(const unsigned char* dongle_key, unsigned int serial, const unsigned char* oxy_pre_cmd, unsigned int oxy_pre_cmd_len, unsigned char* direct_resp, unsigned int direct_resp_size); +XLT_LINK int XLT_API xlt_reserved2(const unsigned char* dongle_key, unsigned int serial, const unsigned char* oxy_pre_cmd, unsigned int oxy_pre_cmd_len, unsigned char* direct_resp, unsigned int direct_resp_size); XLT_LINK int XLT_API xlt_xlightsd_switch_to_nondemo(unsigned int device); //\endcond -//@} //xltapi + +/** +\ingroup xlt_ss +Open a session on the device (see \ref xnd_session_on_xlight). +\param[in] device device index for the selection of a specific XLight device. This value runs from 0 to ::XLT_DEVICE_EXT_MAX -1. +\param[in] password points to a buffer of length ::XLT_PASSWORD_SIZE. It contains the password to be assigned to the device. +\param[out] p_already_open points to an unsigned integer that will contain '1' if the session was already open, and '0' if not. If the pointer p_already_open is set to zero the argument is ignored. +\return returns ::XLT_ERROR_SUCCESS on success, an \ref xlt_Errors "error code" on failure. +\remark if the device referenced is xNodus the argument p_already_open is always ignored. +*/ +XLT_LINK int XLT_API xlt_open_session(unsigned int device, const unsigned char* password, unsigned int* p_already_open); + +/** +\ingroup xlt_ss +Close a session on the device (see \ref xnd_session_on_xlight). +\param[in] device device index for the selection of a specific XLight device. This value runs from 0 to ::XLT_DEVICE_EXT_MAX -1. +\return returns ::XLT_ERROR_SUCCESS on success, an \ref xlt_Errors "error code" on failure. +*/ +XLT_LINK int XLT_API xlt_close_session(unsigned int device); #ifdef __cplusplus @@ -1947,3 +2215,4 @@ XLT_LINK int XLT_API xlt_xlightsd_switch_to_nondemo(unsigned int device); #endif #endif + diff --git a/OxySec/Include/xnd.h b/OxySec/Include/xnd.h new file mode 100644 index 0000000..54c4a83 --- /dev/null +++ b/OxySec/Include/xnd.h @@ -0,0 +1,4055 @@ +// per in out (inout) usa \param[in,out] + +/** \file + * xNodus Library. + * \mainpage xNodus-XLight Library Documentation + \anchor xnd_mainpage + +// \note +> This is the reference manual for the xNodus and 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. + +
      + +

      +This is the documentation of the \ref xnodus_api and \ref xltapi_old "APIs" for the communication between the host computer and the xNodus or XLight device. + +

      +The libraries are supplied in dll and obj format. +- Dlls: xnodus32.dll (32 bit) xnodus.dll (AMD 64 bit) are usable by any application which can be interfaced with DLLs. +- OBJs: xnodus.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 xnd.h and xlt.h and this documentation describes such interfaces. + +

      +The documentation is divided into the following sections: +- \subpage xnodus_doc +- \subpage xn_xlight_library +- \subpage xlt_library "The old XLight APIs documentation (use deprecated)" +*/ + + +#ifndef XND_H_1239854890 +#define XND_H_1239854890 + +#include "xlt.h" + +#ifdef __cplusplus +extern "C" { +#endif + +#ifndef OXY_LONG +#ifdef __LP64__ //MAC +#define OXY_LONG int +#else //__LP64__ +#define OXY_LONG long +#endif //__LP64__ +#endif //OXY_LONG + + +//\cond NOT_COMMENTED +#define XND_LINK XLT_LINK +#define XND_API XLT_API + +#ifndef OPT +#define OPT +#endif + +#ifndef OUT +#define OUT +#endif + +#ifndef INOUT +#define INOUT +#endif +//\endcond + + +/** \defgroup xnodus_errors_misc xNodus miscellaneous errors +\ingroup xnodus_errors +Generic xNodus errors +@{ +*/ +#define XND_ERROR_SUCCESS XLT_ERROR_SUCCESS ///< the operation was successfully completed (alias for the ::XLT_ERROR_SUCCESS value) +#define XND_ERROR_NOT_FOUND XLT_ERROR_NOT_FOUND ///< Device not found. +#define XND_ERROR_INVALID_ARGUMENT XLT_ERROR_INVALID_ARGUMENT ///< Function called with an invalid argument. +#define XND_ERROR_INVALID_STATE XLT_ERROR_INVALID_STATE ///< Invalid state of the device for the required operation. +#define XND_ERROR_TRANSMIT XLT_ERROR_TRANSMIT ///< USB communication error. +#define XND_ERROR_RESOURCE XLT_ERROR_RESOURCE ///< Resource error (usually not enough memory). + + +#define XND_RELEASE_STILL_REFERENCED 1 ///< this is not a real error: returned by the release functions to indicate that the released object is still alive (used by other part of the program) + +#define XND_ERROR_FIND_NO_MORE_DEVICES -2000 ///< returned by xnd_device_find_next(), it indicates that there is no more xNodus device to enumerate and that the search process can be terminated +#define XND_ERROR_FIND_NOT_FOUND_YET -2001 ///< returned by xnd_device_find_next(), it indicates that the search process is still running but at present no further xNodus devices are found + +//@} //xnodus_errors_misc + +/** \defgroup xnodus_errors_authentication xNodus Authentication errors +\ingroup xnodus_errors +Errors that may occurr during a session opening (xnd_xlt_session_open()) + @{ +*/ +#define XND_ERROR_AU_AUTH_USER_NOT_FOUND -2040 ///< the User doesn't exist +#define XND_ERROR_AU_AUTH_PROTOCOL_ERROR -2041 ///< generic protocol error +#define XND_ERROR_AU_SESSION_TEMPORARY_UNAVAILABLE -2042 ///< retry to call the method in a while +#define XND_ERROR_AU_SESSION_NOT_FOUND -2043 ///< an expeceted session is not (or no longer) existing +#define XND_ERROR_AU_SESSION_SRV_ERROR -2044 ///< a session is already running +#define XND_ERROR_AU_SESSION_INVALID_KEY -2045 ///< the cryptographic key is not valid +#define XND_ERROR_AU_SESSION_ALREADY_RUNNING -2046 ///< a session is already running +#define XND_ERROR_AU_AUTH_XNODUS_SERIAL_NOT_FOUND -2047 ///< The AuthUser doesn't exist +#define XND_ERROR_AU_MISSING_KEY -2048 ///< a required cryptographic key is missing +//@} //xnodus_errors_authentication + +/** \defgroup xnodus_errors_communication xNodus communication and network errors +\ingroup xnodus_errors +Communication error returned by the xNodus API library +@{ +*/ +#define XND_ERROR_NET_OPEN_LL_FAILURE -2200 ///< error opening the socket connection +#define XND_ERROR_NET_CONNECT_LL_FAILURE -2201 ///< socket connection failure +#define XND_ERROR_NET_CONNECT_LL_TIMEOUT -2202 ///< timeout while opening the socket connection +#define XND_ERROR_NET_SEND_FAILURE -2203 ///< transmission data to xNodus device failed +#define XND_ERROR_NET_RECV_FAILURE -2204 ///< receiving data from xNodus device failed +#define XND_ERROR_NET_RECV_BAD_FORMAT -2205 ///< bad format of the received data +#define XND_ERROR_CONNECTION_ABORTED -2206 ///< socket connection aborted by the API +#define XND_ERROR_NET_DNS_FAILURE -2210 ///< DNS resolution address failed +#define XND_ERROR_INVALID_SUBNET_MASK -2211 ///< wrong subnet mask (this error may occur searching for xNodus device) +#define XND_ERROR_UNKNOWN_TARGET -2212 ///< connecting to an unknown device +//@} //xnodus_errors_communication + +/** \defgroup xnodus_errors_device xNodus errors returned by the device +\ingroup xnodus_errors +Errors returned directly by the xNodus device and passed back by the APIs +@{ +*/ +#define XND_DEV_BASE_ERR -3000 ///< offset value for the errors returned by the device + + +#define XND_ERROR_DEV_INVALID_ARGUMENT (XND_DEV_BASE_ERR -0x01) ///< invalid argument in a command #XND_DEV_BASE_ERR +#define XND_ERROR_DEV_INVALID_COMMAND (XND_DEV_BASE_ERR -0x02) ///< invalid command for the current status of the device +#define XND_ERROR_DEV_INVALID_COMMAND_SIGNATURE (XND_DEV_BASE_ERR -0x03) ///< corrupted command +#define XND_ERROR_DEV_INVALID_SEQUENCE_NUMBER (XND_DEV_BASE_ERR - 0x04) ///< command reused or synchronization lost between client and device +#define XND_ERROR_DEV_INVALID_DESTINATION (XND_DEV_BASE_ERR - 0x05) ///< an internal error (you shouldn't ever get) +#define XND_ERROR_DEV_INVALID_KEY_TYPE (XND_DEV_BASE_ERR - 0x06) ///< wrong or non supported type of the cryptographic key used +#define XND_ERROR_DEV_INVALID_DEVICE_STATUS (XND_DEV_BASE_ERR - 0x07) ///< status of the device invalid for the issued command +#define XND_ERROR_DEV_RESET_IN_PROGRESS (XND_DEV_BASE_ERR - 0x08) ///< the device cannot work because it is about to be reset (this happen only during device maintenance, configuration, or firmware update) +#define XND_ERROR_DEV_DEVICE_IS_EXPIRED (XND_DEV_BASE_ERR - 0x09) ///< the device license is expired +#define XND_ERROR_DEV_INVALID_COMMAND_COUNTER (XND_DEV_BASE_ERR - 0x0A) ///< invalid counter value for the remote command (the passed value is not greater than the xNodus internal value returned by xnd_get_info(), structure ::XND_INFO parameter 'remote_counter') +#define XND_ERROR_DEV_INVALID_SERIAL_NUMBER (XND_DEV_BASE_ERR - 0x0B) ///< the serial number doesn't match the expected one +#define XND_ERROR_DEV_INVALID_XLIGHT_INSTANCE (XND_DEV_BASE_ERR - 0x0C) ///< the referenced virtual XLight on xNodus doesn't exist +#define XND_ERROR_DEV_RSA_INTERNAL_ERROR (XND_DEV_BASE_ERR - 0x0D) ///< generic RSA internal error +#define XND_ERROR_DEV_RSA_KEY_ABSENT (XND_DEV_BASE_ERR - 0x0E) ///< the needed RSA key is not present in the device +#define XND_ERROR_DEV_RSA_INVALID_KEY_LEN (XND_DEV_BASE_ERR - 0x0F) ///< the cryptographic key length doesn't match the expected value +#define XND_ERROR_AES_INVALID_KEY_LEN (XND_DEV_BASE_ERR - 0x10) ///< the cryptographic key length doesn't match the expected value +#define XND_ERROR_AES_KEY_ABSENT (XND_DEV_BASE_ERR - 0x11) ///< the needed AES key is not present in the device +#define XND_ERROR_DEV_INTERNAL_ERROR (XND_DEV_BASE_ERR - 0xFF) ///< generic internal error (this should never occur) + + +#define XND_ERROR_DEV_USER_INVALID_TYPE (XND_DEV_BASE_ERR - 0x1003) ///< the user is not of the expected type for the function to be done +#define XND_ERROR_DEV_USER_INVALID_XLT_INDEX (XND_DEV_BASE_ERR - 0x1004) ///< a users refer to a non existing virtual XLight device +#define XND_ERROR_DEV_USER_NAME_ALREADY_EXIST (XND_DEV_BASE_ERR - 0x1005) ///< the user already exist (attempt to create an already existing user) +#define XND_ERROR_DEV_USER_NO_MORE_SESSIONS_AVAILABLE (XND_DEV_BASE_ERR - 0x1006) ///< the attempt to open a session failed because the limit of the licenses for the user is reached +#define XND_ERROR_DEV_USER_NO_SESSION_TO_CLOSE (XND_DEV_BASE_ERR - 0x1007) ///< no session of the user can be closed +#define XND_ERROR_DEV_USER_NO_MORE_MODULES_AVAILABLE (XND_DEV_BASE_ERR - 0x1008) ///< the attempt to access to a module failed because the limit of the licenses is reached +#define XND_ERROR_DEV_USER_EXPIRED (XND_DEV_BASE_ERR - 0x1009) ///< the session cannot be open because the user timelife is expired +#define XND_ERROR_DEV_USER_NOT_PRESENT (XND_DEV_BASE_ERR - 0x100A) ///< the attempt to open a session failed because the user is not recognized by xNodus +#define XND_ERROR_DEV_USER_NO_MORE_USER_AVAILABLE (XND_DEV_BASE_ERR - 0x100B) ///< it is impossible create a new user because the device already contains the maximum allowed number of user +#define XND_ERROR_DEV_USER_INVALID_NAME (XND_DEV_BASE_ERR - 0x100C) ///< an action of the user requests a change on a different user without permission +#define XND_ERROR_DEV_USER_ACCESS_DENIED (XND_DEV_BASE_ERR - 0x100E) ///< attempted to run a function not allowed to the current user +#define XND_ERROR_DEV_USER_OXY_LICENSES_EXPIRED (XND_DEV_BASE_ERR - 0x1010) ///< Oxysec license period for the usage of users is expired (a renewal is necessary) + +#define XND_ERROR_DEV_SESSION_NO_MORE_SESSIONS_AVAILABLE (XND_DEV_BASE_ERR - 0x2001) ///< the attempt to open a session failed because the limit of the licenses is reached +#define XND_ERROR_DEV_SESSION_INVALID_SESSION_ID (XND_DEV_BASE_ERR - 0x2004) ///< the session of the issued command doesn't exist or it is expired +#define XND_ERROR_DEV_SESSION_INVALID_SESSION_STATUS (XND_DEV_BASE_ERR - 0x2005) ///< a command was sent when an authenticated session opening is not complete +#define XND_ERROR_DEV_SESSION_INVALID_CHALLENGE (XND_DEV_BASE_ERR - 0x2006) ///< the authentication process failed for an invalid challenge check +#define XND_ERROR_DEV_SESSION_INVALID_SIGNATURE (XND_DEV_BASE_ERR - 0x2007) ///< a client signature sent during authenticated session opening is wrong +#define XND_ERROR_DEV_SESSION_TIMEOUT_EXPIRED (XND_DEV_BASE_ERR - 0x2008) ///< the session timeout is expired (the session is no longer available) +#define XND_ERROR_DEV_SESSION_NOT_ENOUGH_LICENSES_AVAILABLE (XND_DEV_BASE_ERR - 0x2009) ///< OxySec license number reached (it is impossible assign the requested number of license because the available amount would be exceeded) +#define XND_ERROR_DEV_SESSION_NO_MORE_SESSION_AVAILABLE (XND_DEV_BASE_ERR - 0x2012) ///< No more session can be established because the phisical limit of the device has been found + +#define XND_ERROR_DEV_SESSION_VK_INVALID_ALGO_TYPE (XND_DEV_BASE_ERR - 0x200A) ///< non existing algorithm id chosen for volatile key +#define XND_ERROR_DEV_SESSION_VK_INVALID_KEY_LEN (XND_DEV_BASE_ERR - 0x200C) ///< invalid key len of a volatile key +#define XND_ERROR_DEV_SESSION_VK_INVALID_DATA_LEN (XND_DEV_BASE_ERR - 0x200D) ///< invalid data length for encryption (it must be a multiple of 16) +#define XND_ERROR_DEV_SESSION_VK_INVALID_HEADER_SIZE (XND_DEV_BASE_ERR - 0x200E) ///< inviled header length for GCM encryption (it must be a multiple of 16) +#define XND_ERROR_DEV_SESSION_INVALID_CHECK_COUNTER (XND_DEV_BASE_ERR - 0x200F) ///< the counter is invalid in xnd_continue_session_check() call +#define XN_ERROR_SESSION_VK_INVALID_SIGNATURE (XND_DEV_BASE_ERR - 0x2019) ///< the GCM of a GCM decryption is not as expected (the data are corrupted) + +#define XND_ERROR_DEV_MODULE_ALREADY_OPENED (XND_DEV_BASE_ERR - 0x3003) ///< the module is already open (and cannot be open again) +#define XND_ERROR_DEV_MODULE_INVALID_INDEX (XND_DEV_BASE_ERR - 0x3004) ///< non existing module referred +#define XND_ERROR_DEV_MODULE_NO_FREE_MODULE (XND_DEV_BASE_ERR - 0x3005) ///< no more license available for the module +#define XND_ERROR_DEV_MODULE_EXPIRED (XND_DEV_BASE_ERR - 0x3007) ///< the license time of the module is expired + +#define XND_ERROR_DEV_LICENSE_MULTI_INSTANCE_INTERNAL_ERROR (XND_DEV_BASE_ERR - 0x2010) ///< an internal error occurred running a multi-instance session (see \ref xnd_users_group_lic) +#define XND_ERROR_DEV_LICENSE_MULTI_INSTANCE_NO_SESSION_TO_CLOSE (XND_DEV_BASE_ERR - 0x2011) ///< there is no actual session to close in a multi-instance session management (see \ref xnd_users_group_lic) +#define XND_ERROR_DEV_LICENSE_MULTI_INSTANCE_INVALID_CLIENT (XND_DEV_BASE_ERR - 0x2014) ///< the connected client is invalid +#define XND_ERROR_DEV_LICENSE_MULTI_INSTANCE_INVALID_RND (XND_DEV_BASE_ERR - 0x2015) ///< instance protocol error +#define XND_ERROR_DEV_LICENSE_MULTI_INSTANCE_NO_SESSION_AVAILABLE (XND_DEV_BASE_ERR - 0x2016) ///< Can't open a new instance, the computer has reached the maximum number of instances allowed +#define XND_ERROR_DEV_LICENSE_LICENSE_INVALID_INSTANCE_QUANTITY (XND_DEV_BASE_ERR - 0x2017) ///< the configured number of instance exceed the allowed limit (64 instances) + +#define XND_ERROR_LICENSE_LOG_END (XND_DEV_BASE_ERR - 0x2018) ///< the log list is completed + +//#define XND_ERROR_MODULE_INTERNAL_ERROR (XND_DEV_BASE_ERR - 0x30FF) // internal + +//@} //xnodus_errors_device + + + +/** +\defgroup xnd_RSA_const xNodus RSA size constant +\ingroup xnodus_defines + +These are the constants for the various size of the RSA key managed by xNodus APIs that +extend the XLight definitions + +@{ +*/ +#define XND_RSA_2048_BIT_SIZE 2048 ///< number of bits of the public modulus of a 2048 bit RSA key +#define XND_RSA_2048_PUB_KEY_SIZE 260 ///0 +\param[out] p_status points to an integer that will receive the status of the operation: ::XND_ERROR_SUCCESS on success, an \ref xnodus_errors "error code" on failure. +\return a ::XND_DEVICE_FIND handle on success, zero otherwise, p_status will point to the occurred error. + +\remark If the entry label is specified only xNodus devices with that label (i.e. its identification name) are found. + +\remark The port entry needs to be specified only if the argument label is set. If port has an uncorrect value it is not possible verify the label of the xNodus device. + +\remark The remember_found_devices instruct the API to keep track of the found device in the registry to speed up successive device search. + +\remark The memory referenced by the ::XND_DEVICE_FIND handle returned by this function must be freed with xnd_device_find_stop(). +\see xnd_device_find_next(), xnd_device_find_finalize(). +*/ +XND_LINK XND_DEVICE_FIND XND_API xnd_device_find_create(XND_XLT_ENV env, unsigned int remember_found_devices, OPT unsigned short port, OPT const unsigned char* label, OPT OUT int* p_status); + +//\cond NOT_COMMENTED +XND_LINK XND_DEVICE_FIND XND_API xnd_device_find_create2(XND_XLT_ENV env, unsigned int remember_found_devices, XND_IN_ADDR hint_subnet, XND_IN_ADDR hint_subnet_mask, OPT unsigned short port, OPT const unsigned char* label, OPT OUT int* p_status); +//\endcond + +/** +\ingroup xnodus_find_devices +Return the address of an xNodus device found in the local network. +See \ref searching_xnodus for an usage example. +\param[in] ctx a ::XND_DEVICE_FIND handle generated by xnd_device_find_create(). +\param[in] timeout_msec maximum time allowed to find an xNodus device. +\param[out] sock_addr points to structure receiving the IPv4 address of the found device. +\return ::XND_ERROR_SUCCESS on success, an \ref xnodus_errors "error code" on failure. If the timeout is expired but the network is not completely explored (so some devices may be still found) the value XND_ERROR_FIND_NOT_FOUND_YET is returned. + +\see xnd_device_find_create(), xnd_device_find_finalize(). +*/ +XND_LINK int XND_API xnd_device_find_next(XND_DEVICE_FIND ctx, unsigned int timeout_msec, OUT XND_IN_ADDR* sock_addr); + +/** +\ingroup xnodus_find_devices +Stop the xNodus device search. +See \ref searching_xnodus for an usage example. +\param[in] ctx a ::XND_DEVICE_FIND handle generated by xnd_device_find_create(). +\remark This is an optional function, it helps xnd_in_device_find_finalize() to run faster if called many milliseconds before it. +This function instructs the searching threads launched by xnd_device_find_create() to terminate the xNodus device search. +*/ +XND_LINK void XND_API xnd_device_find_stop(XND_DEVICE_FIND ctx); + +/** +\ingroup xnodus_find_devices +Complete an xNodus device search. +See \ref searching_xnodus for an usage example. +\param[in] ctx a XND_DEVICE_FIND handle generated by xnd_device_find_create(). +\see xnd_device_find_create(), xnd_device_find_next(). +*/ +XND_LINK void XND_API xnd_device_find_finalize(XND_DEVICE_FIND ctx); + + + +///////////////////////////////////////// +// network data functions (possibly in future IPV6 support) + +//network data + +/** +\defgroup xnd_protocol_type Protocol types +\ingroup xnodus_defines + +Type of protocol to be used during the communication to the xNodus device. At present only one protocol based on TCP-IP is supported. + +@{ +*/ +#define XND_NET_PROTOCOL_UNKNOWN 0 ///< unknown protocol +#define XND_NET_PROTOCOL_TCP 1 ///< TCP basic xNodus protocol +#define XND_NET_PROTOCOL_UDP 2 ///< UDP basic xNodus protocol + +//@} + + +/** +\ingroup xnodus_net_func +Create a ::XND_NET_DATA handle. +\param[in] env xNodus environment handle (see xnd_xlt_env_create()). +\param[in] addr_port a pointer to the null terminated name of the host to resolve and the port expressed as \.\. +\param[in] protocol_type the communication protocol type to be used. If the value is set to zero the default ::XND_NET_PROTOCOL_TCP is used. +\param[in] recv_to_msec the timeout for getting answer from the xNodus device. +\param[out] p_status points to an integer that will receive the status of the operation: ::XND_ERROR_SUCCESS on success, an \ref xnodus_errors "error code" on failure. +\return a ::XND_NET_DATA handle. +\remark The argument addr_port is a string of the form \.\, for instance: 192.168.0.125:15678 or foo.example.com:15600. +\remark The returned ::XND_NET_DATA handle must be freed calling xnd_net_data_release(). +\remark Setting recv_to_msec to 0 the default value (5000 milliseconds) is used. +\see xnd_net_data_release(), xnd_net_data_acquire() +*/ +XND_LINK XND_NET_DATA XND_API xnd_net_data_create_from_addr_port(XND_XLT_ENV env, const char* addr_port, OPT unsigned int protocol_type, OPT unsigned int recv_to_msec, OPT OUT int* p_status); + +/** +\ingroup xnodus_net_func +Create a ::XND_NET_DATA handle and immediately resolve the address. +\param[in] env xNodus environment handle (see xnd_xlt_env_create()). +\param[in] addr_port a pointer to the null terminated name of the host to resolve and the port expressed as \.\. +\param[in] protocol_type the communication protocol type to be used. If set to zero the default value is used (::XND_NET_PROTOCOL_TCP). +\param[in] recv_to_msec the timeout for getting answer from the xNodus device. If set to zero the default value is used (5000 msec). +\param[out] p_status points to an integer that will receive the status of the operation: ::XND_ERROR_SUCCESS on success, an \ref xnodus_errors "error code" on failure. +\return a ::XND_NET_DATA handle. + +\remark This command is similar to xnd_net_data_create_from_addr_port() but it immediately resolve the address. If it is not possible the function immediately fails. +\remark The returned ::XND_NET_DATA handle must be freed calling xnd_net_data_release(). + +\see xnd_net_data_create_from_addr_port(). +*/ +XND_LINK XND_NET_DATA XND_API xnd_net_data_create_resolving_addr_port(XND_XLT_ENV env, const char* addr_port, OPT unsigned int protocol_type, OPT unsigned int recv_to_msec, OPT OUT int* p_status); + +/** +\ingroup xnodus_net_func +Create a ::XND_NET_DATA handle. It represent an xNodus device in the local network. The address is resolved when the xnd_net_data_get_addr() function is called. +\param[in] env xNodus environment handle (see xnd_xlt_env_create()). +\param[in] port the TCP/IP port used by the searched xNodus device. +\param[in] label the xNodus label of the searched device. If a NULL pointer is set the label is ignored and any found device is considered regardless the label. +\param[in] search_timeout_msec the maximum time expressed in millisecond that the searching procedure may take. If this value is set to zero there is no such limit. +\param[in] protocol_type the communication protocol type to be used. If set to zero the default value is used (::XND_NET_PROTOCOL_TCP). +\param[in] recv_to_msec the timeout for getting answer from the xNodus device. If set to zero the default value is used (5000 msec). +\param[out] p_status points to an integer that will receive the status of the operation: ::XND_ERROR_SUCCESS on success, an \ref xnodus_errors "error code" on failure. +\return a ::XND_NET_DATA handle. +\remark The returned ::XND_NET_DATA handle must be freed calling xnd_net_data_release(). +\see xnd_net_data_create_from_addr_port(). +*/ +XND_LINK XND_NET_DATA XND_API xnd_net_data_create_local_search(XND_XLT_ENV env, unsigned short port, OPT const unsigned char* label, OPT unsigned int search_timeout_msec, OPT unsigned int protocol_type, OPT unsigned int recv_to_msec, OPT OUT int* p_status); + +/** +\ingroup xnodus_net_func +Create a ::XND_NET_DATA handle and immediately search an xNodus device in the local network. +\param[in] env xNodus environment handle (see xnd_xlt_env_create()). +\param[in] port the TCP/IP port used by the searched xNodus device. +\param[in] label the xNodus label of the searched device. If a NULL pointer is set the label is ignored and any found device is considered regardless the label. +\param[in] search_timeout_msec the maximum time expressed in millisecond that the searching procedure may take. If this value is set to zero there is no such limit. +\param[in] protocol_type the communication protocol type to be used. If set to zero the default value is used (::XND_NET_PROTOCOL_TCP). +\param[in] recv_to_msec the timeout for getting answer from the xNodus device. If set to zero the default value is used (5000 msec). +\param[out] p_status points to an integer that will receive the status of the operation: ::XND_ERROR_SUCCESS on success, an \ref xnodus_errors "error code" on failure. +\return a ::XND_NET_DATA handle. + +\remark This command is similar to xnd_net_data_create_local_search() but it immediately resolve the address. If it is not possible the +function immediately fails. +\remark The returned ::XND_NET_DATA handle must be freed calling xnd_net_data_release(). +\see xnd_net_data_create_local_search(), xnd_net_data_create_from_addr_port(). +*/ +XND_LINK XND_NET_DATA XND_API xnd_net_data_create_resolving_local_search(XND_XLT_ENV env, unsigned short port, OPT const unsigned char* label, OPT unsigned int search_timeout_msec, OPT unsigned int protocol_type, OPT unsigned int recv_to_msec, OPT OUT int* p_status); + +/** +\ingroup xnodus_net_func +Create a XND_NET_DATA handle from an IPv4 address. +\param[in] env xNodus environment handle (see xnd_xlt_env_create()). +\param[in] sock_addr a pointer to a ::XND_SOCK_ADDR struct. +\param[in] protocol_type the communication protocol type to be used. If set to zero the default value is used (::XND_NET_PROTOCOL_TCP). +\param[in] recv_to_msec the timeout for getting answer from the xNodus device. If set to zero the default value is used (5000 msec). +\param[out] p_status points to an integer that will receive the status of the operation: ::XND_ERROR_SUCCESS on success, an \ref xnodus_errors "error code" on failure. +\return a ::XND_NET_DATA handle. +\remark The returned ::XND_NET_DATA handle must be freed calling xnd_net_data_release(). +*/ +XND_LINK XND_NET_DATA XND_API xnd_net_data_create_from_sock_addr(XND_XLT_ENV env, const XND_SOCK_ADDR* sock_addr, OPT unsigned int protocol_type, OPT unsigned int recv_to_msec, OPT OUT int* p_status); + +/** +\ingroup xnodus_net_func +Acquire a net data object pointed by a ::XND_NET_DATA handle (see \ref xnd_create_acquire_release). +\param[in] ctx a ::XND_NET_DATA handle referencing the object to acquire. +\return on success a reference to the input ::XND_NET_DATA handle, '0' otherwise. +\remark The reference to the ::XND_NET_DATA handle obtained by this function must be freed calling xnd_net_data_release(). +*/ +XND_LINK XND_NET_DATA XND_API xnd_net_data_acquire(XND_NET_DATA ctx); + +/** +\ingroup xnodus_net_func +Release a net data object pointed by a ::XND_NET_DATA handle (see \ref xnd_create_acquire_release). +\param[in] ctx the ::XND_NET_DATA handle referencing to the object to release. +\return ::XND_ERROR_SUCCESS on success, an \ref xnodus_errors "error code" on failure, and ::XND_RELEASE_STILL_REFERENCED if there are still reference to the object. +\remark When the reference to the object represented by the ::XND_NET_DATA are. +all removed the object are automatically freed. +\remark When ::XND_RELEASE_STILL_REFERENCED are returned the operation may be considered as correctly completed and no further action must be taken. +This is just a way to inform that there is at least one reference to the object and that the object will be deleted only when the last xnd_net_data_release() call will be issued. +*/ +XND_LINK int XND_API xnd_net_data_release(XND_NET_DATA ctx); + +/** +\ingroup xnodus_net_func +Return the IPv4 address and port number related to a ::XND_NET_DATA handle. +\param[in] ctx the ::XND_NET_DATA handle referencing the object to release. +\param[out] sock_addr points to a ::XND_SOCK_ADDR structure that will receive the address and port related to the handle. +\return ::XND_ERROR_SUCCESS on success, an \ref xnodus_errors "error code" on failure. +*/ +XND_LINK int XND_API xnd_net_data_get_addr(XND_NET_DATA ctx, P_XND_SOCK_ADDR sock_addr); + +//\cond NOT_COMMENTED +XND_LINK unsigned char* XND_API xnd_net_data_to_bytes_alloc(XND_NET_DATA ctx, unsigned int* p_len); +XND_LINK XND_NET_DATA XND_API xnd_net_data_from_bytes_create(XND_XLT_ENV env, const unsigned char* data, unsigned int data_len); +//\endcond + + + +//xnodus_net_func + +///////////////////////////////////////////////////////////////////////////////////////// +//Key types for key data + +/** \defgroup xnd_key_data_types Cryptographic key types for key data objects +\ingroup xnodus_defines +Cryptographic key types for ::XND_KEY_DATA objects +@{ +*/ +#ifndef XND_KD_KEY_TYPE_NO_KEY +#define XND_KD_KEY_TYPE_NO_KEY 0 ///< no key +#define XND_KD_KEY_TYPE_AES 1 ///< AES 256 key type +#define XND_KD_KEY_TYPE_RSA_PUB 2 ///< RSA public key (of any size) +#define XND_KD_KEY_TYPE_RSA_PRIV 3 ///< RSA private key (of any size) +#endif //XND_KD_KEY_TYPE_NO_KEY +//@} //xnd_key_data_types + +//SERVICE FUNCTIONS TO BUILD KEY DATA + + +//xnodus_crypto_key_man + +/** +\ingroup xnodus_crypto_key_man +Create a key data object from a string representation of the key. +\param[in] env xNodus environment handle (see xnd_xlt_env_create()). +\param[in] key_blob_data points string containing the key in encoded form. +\param[in] wrap_key_string points to a string used as password for decrypting 'key_blob_data'. This argument is optional and can be set to 0. +\param[out] p_status points to an integer that will receive the status of the operation: ::XND_ERROR_SUCCESS on success, an \ref xnodus_errors "error code" on failure. +\return a ::XND_KEY_DATA handle which points to an allocated key data representing the 'key_blob_data' entry. Use xnd_keydata_release() to release the returned object. +\note 'key_blob_data' is a base 64 representation of a key object. Such representation can be encrypted and in this case the argument 'wrap_key_string' must point to the unwrapping key. +\see \ref xnd_key_data. +*/ +XND_LINK XND_KEY_DATA XND_API xnd_keydata_from_keyblob_create(XND_XLT_ENV env, const char* key_blob_data, OPT const char* wrap_key_string, OPT OUT int* p_status); + +/** +\ingroup xnodus_crypto_key_man +Create a key data object from a string representation of the key. +\param[in] env xNodus environment handle (see xnd_xlt_env_create()). +\param[in] key_blob_data points string containing the key in encoded form. +\param[in] wrap_key points to a ::XND_KEY_DATA object containing the cryptographic key for decrypting 'key_blob_data'. This argument is optional and can be set to 0. +\param[out] p_status points to an integer that will receive the status of the operation: ::XND_ERROR_SUCCESS on success, an \ref xnodus_errors "error code" on failure. +\return a ::XND_KEY_DATA handle which points to an allocated key data representing the 'key_blob_data' entry. Use xnd_keydata_release() to release the returned object. +\note 'key_blob_data' is a base 64 representation of a key object. Such representation can be encrypted and in this case the argument 'wrap_key' must point to the unwrapping key. +\see \ref xnd_key_data. +*/ +XND_LINK XND_KEY_DATA XND_API xnd_keydata_from_keyblob_create2(XND_XLT_ENV env, const char* key_blob_data, XND_KEY_DATA wrap_key, OPT OUT int* p_status); + +/** +\ingroup xnodus_crypto_key_man +Create a key data object from a key represented in XLight RSA format (see \ref xnd_key_data). +\param[in] env xNodus environment handle (see xnd_xlt_env_create()). +\param[in] priv_key points to a buffer containing the RSA private key specified in XLight format. +\param[in] priv_key_len the length of the key pointed by 'priv_key' argument. +\param[out] p_status points to an integer that will receive the status of the operation: ::XND_ERROR_SUCCESS on success, an \ref xnodus_errors "error code" on failure. +\return a ::XND_KEY_DATA handle which points to an allocated key data representing the passed input. Use xnd_keydata_release() to release the returned object. +\see \ref xnd_key_data. +*/ +XND_LINK XND_KEY_DATA XND_API xnd_keydata_rsa_xlt_priv_key_create(XND_XLT_ENV env, const unsigned char* priv_key, unsigned int priv_key_len, OPT OUT int* p_status); + +/** +\ingroup xnodus_crypto_key_man +Create a key data object from a key represented in PQE format (see \ref xnd_key_data). +\param[in] env xNodus environment handle (see xnd_xlt_env_create()). +\param[in] priv_key points to a buffer containing the RSA private key specified in PQE format. +\param[in] priv_key_len the length of the key pointed by 'priv_key' argument. +\param[out] p_status points to an integer that will receive the status of the operation: ::XND_ERROR_SUCCESS on success, an \ref xnodus_errors "error code" on failure. +\return a ::XND_KEY_DATA handle which points to an allocated key data representing the passed input. Use xnd_keydata_release() to release the returned object. +\see \ref xnd_key_data. +*/ +XND_LINK XND_KEY_DATA XND_API xnd_keydata_rsa_pqe_priv_key_create(XND_XLT_ENV env, const unsigned char* priv_key, unsigned int priv_key_len, OPT OUT int* p_status); + +/** +\ingroup xnodus_crypto_key_man +Check if a supposed RSA private key is correct. + +It is not tested only the type of the object, but the key values are checked. +\param[in] key_data the ::XND_KEY_DATA handle referencing to the key object to check. +\return ::XND_ERROR_SUCCESS on success, an \ref xnodus_errors "error code" on failure. +\see \ref xnd_key_data. +*/ +XND_LINK int XND_API xnd_keydata_rsa_priv_key_is_correct(XND_KEY_DATA key_data); + +/** +\ingroup xnodus_crypto_key_man +Create a key data object of a RSA public key derived from its private key. +\param[in] key_data the ::XND_KEY_DATA handle of a private RSA key +\param[out] p_status points to an integer that will receive the status of the operation: ::XND_ERROR_SUCCESS on success, an \ref xnodus_errors "error code" on failure. +\return a ::XND_KEY_DATA handle which points to the allocated key data representing the public key. Use xnd_keydata_release() to release the returned object. +\see \ref xnd_key_data. +*/ +XND_LINK XND_KEY_DATA XND_API xnd_keydata_rsa_pub_key_from_priv_create(XND_KEY_DATA key_data, OPT OUT int* p_status); + +/** +\ingroup xnodus_crypto_key_man +Create a key data object of a RSA public from a buffer representation of the key (see \ref xnd_key_data). +\param[in] env xNodus environment handle (see xnd_xlt_env_create()). +\param[in] pub_key points to a buffer containing the RSA public key in buffer format. +\param[in] pub_key_len the length in bytes of the buffer pointed by 'pub_key'. +\param[out] p_status points to an integer that will receive the status of the operation: ::XND_ERROR_SUCCESS on success, an \ref xnodus_errors "error code" on failure. +\return a ::XND_KEY_DATA handle which points to the allocated key data representing the public key. Use xnd_keydata_release() to release the returned object. +\see \ref xnd_key_data. +*/ +XND_LINK XND_KEY_DATA XND_API xnd_keydata_rsa_pub_key_create(XND_XLT_ENV env, const unsigned char* pub_key, unsigned int pub_key_len, OPT OUT int* p_status); + +/** +\ingroup xnodus_crypto_key_man +Create a key data object representing an AES key (see \ref xnd_key_data). +\param[in] env xNodus environment handle (see xnd_xlt_env_create()). +\param[in] key points to a 32 byte buffer containing the AES key. +\param[out] p_status points to an integer that will receive the status of the operation: ::XND_ERROR_SUCCESS on success, an \ref xnodus_errors "error code" on failure. +\return a ::XND_KEY_DATA handle which points to the allocated key data representing the symmetric AES key. Use xnd_keydata_release() to release the returned object. +\see \ref xnd_key_data. +*/ +XND_LINK XND_KEY_DATA XND_API xnd_keydata_aes_key_create(XND_XLT_ENV env, const unsigned char* key, OPT OUT int* p_status); + +/** +\ingroup xnodus_crypto_key_man +Create a key data object representing an AES key derived from a printable string used as a password for unwrapping the user data keys (see \ref xnd_deferring_wrap_key). +\param[in] env xNodus environment handle (see xnd_xlt_env_create()). +\param[in] wrap_key_string the wrapping string +\param[out] p_status points to an integer that will receive the status of the operation: ::XND_ERROR_SUCCESS on success, an \ref xnodus_errors "error code" on failure. +\return a ::XND_KEY_DATA handle which points to the allocated key data representing the symmetric AES key used to unwrap user data. Use xnd_keydata_release() to release the returned object. +\see \ref xnd_key_data. +*/ +XND_LINK XND_KEY_DATA XND_API xnd_keydata_create_from_wrapstring(XND_XLT_ENV env, const char* wrap_key_string, OPT OUT int* p_status); + +/** +\ingroup xnodus_crypto_key_man +Acquire a key data object pointed by a ::XND_KEY_DATA handle (see \ref xnd_create_acquire_release). +\param[in] key_data the ::XND_KEY_DATA handle referencing to the object to acquire. +\return the 'key_data' handle to the object on success, '0' on error. +\remark The reference to the ::XND_KEY_DATA handle obtained by this function must be freed calling xnd_keydata_release(). +*/ +XND_LINK XND_KEY_DATA XND_API xnd_keydata_acquire(XND_KEY_DATA key_data); + +/** +\ingroup xnodus_crypto_key_man +Release a key data object pointed by a ::XND_KEY_DATA handle (see \ref xnd_create_acquire_release). +\param[in] key_data the ::XND_KEY_DATA handle referencing to the object to release. +\return ::XND_ERROR_SUCCESS on success, an \ref xnodus_errors "error code" on failure, and ::XND_RELEASE_STILL_REFERENCED if there are still reference to the object. +*/ +XND_LINK int XND_API xnd_keydata_release(XND_KEY_DATA key_data); + +/** +\ingroup xnodus_crypto_key_man +Return the type of the key contained in the object. +\param[in] key_data the ::XND_KEY_DATA handle referencing to the object. +\return a value in \ref xnd_key_data_types to specify the type of the key +*/ +XND_LINK unsigned int XND_API xnd_keydata_get_type(XND_KEY_DATA key_data); + +/** +\ingroup xnodus_crypto_key_man +Return the type of the key contained in the object expressing such value from \ref xnd_info_key_type values. +\param[in] key_data the ::XND_KEY_DATA handle referencing to the object. +\return a value in \ref xnd_info_key_type to specify the type of the key +*/ +XND_LINK unsigned int XND_API xnd_keydata_get_info_type(XND_KEY_DATA key_data); + +/** +\ingroup xnodus_crypto_key_man +Create a key data object from the formatted value returned by the 'info' structure xNodus (::XND_INFO and ::XND_USER_INFO). +\param[in] env xNodus environment handle (see xnd_xlt_env_create()). +\param[in] info_key_type a value from \ref xnd_info_key_type. +\param[in] key points to a buffer containing the formatted key expressed with type 'info_key_type'. +\param[in] key_len the length in bytes of the buffer pointed by 'key'. +\param[out] p_status points to an integer that will receive the status of the operation: ::XND_ERROR_SUCCESS on success, an \ref xnodus_errors "error code" on failure. +\return a ::XND_KEY_DATA handle which points to the allocated key data representing the key. Use xnd_keydata_release() to release the returned object. +\see \ref xnd_key_data. +*/ +XND_LINK XND_KEY_DATA XND_API xnd_keydata_create_from_keyinfo(XND_XLT_ENV env, unsigned int info_key_type, const unsigned char* key, unsigned int key_len, OPT OUT int* p_status); + +/** +\ingroup xnodus_crypto_key_man +Return the AES key from a key data object. +\param[in] key_data the handle of type ::XND_KEY_DATA which points to the key data object. +\param[out] key points to a buffer that will receive the AES key. +\param[in] key_size the size in bytes of the buffer pointed by 'key'. +\param[out] p_key_len points to an unsigned integer which will receive the length of the AES key (always 32). This pointer may be set to 0. +\return ::XND_ERROR_SUCCESS on success, an \ref xnodus_errors "error code" on failure, if the key contained in the object is not an AES key the function fails with error ::XLT_ERROR_INVALID_STATE. +\remark The unsigned integer pointed by 'p_key_len' receive the size of the key even if key_size is shorter and the function fails. +\see \ref xnd_key_data. +*/ +XND_LINK int XND_API xnd_keydata_get_as_aes_key(XND_KEY_DATA key_data, OUT unsigned char* key, unsigned int key_size, unsigned int* p_key_len); + +/** +\ingroup xnodus_crypto_key_man +Return the public RSA key from a key data object. +\param[in] key_data the handle of type ::XND_KEY_DATA which points to the key data object. +\param[out] key points to a buffer that will receive the public RSA key. +\param[in] key_size the size in bytes of the buffer pointed by 'key'. +\param[out] p_key_len points to an unsigned integer which will receive the length of the public RSA key . This pointer may be set to 0. +\return ::XND_ERROR_SUCCESS on success, an \ref xnodus_errors "error code" on failure, if the key contained in the object is not a public RSA key the function fails with error ::XLT_ERROR_INVALID_STATE. +\remark The unsigned integer pointed by 'p_key_len' receive the size of the key even if key_size is shorter and the function fails. +\see \ref xnd_key_data. +*/ +XND_LINK int XND_API xnd_keydata_get_as_formatted_rsa_pub_key(XND_KEY_DATA key_data, OUT unsigned char* key, unsigned int key_size, unsigned int* p_key_len); + +/** +\ingroup xnodus_crypto_key_man +Return the private RSA key from a key data object in PQE format (see \ref xnd_users_key). +\param[in] key_data the handle of type ::XND_KEY_DATA which points to the key data object. +\param[out] key points to a buffer that will receive the private RSA key. +\param[in] key_size the size in bytes of the buffer pointed by 'key'. +\param[out] p_key_len points to an unsigned integer which will receive the length of the private RSA key . This pointer may be set to 0. +\return ::XND_ERROR_SUCCESS on success, an \ref xnodus_errors "error code" on failure, if the key contained in the object is not a private RSA key the function fails with error ::XLT_ERROR_INVALID_STATE. +\remark The unsigned integer pointed by 'p_key_len' receive the size of the key even if key_size is shorter and the function fails. +\see \ref xnd_key_data. +*/ +XND_LINK int XND_API xnd_keydata_get_as_formatted_rsa_pqe_priv_key(XND_KEY_DATA key_data, OUT unsigned char* key, unsigned int key_size, unsigned int* p_key_len); + +/** +\ingroup xnodus_crypto_key_man +Return the private RSA key from a key data object in XLight format (see \ref xnd_users_key). +\param[in] key_data the handle of type ::XND_KEY_DATA which points to the key data object. +\param[out] key points to a buffer that will receive the private RSA key. +\param[in] key_size the size in bytes of the buffer pointed by 'key'. +\param[out] p_key_len points to an unsigned integer which will receive the length of the private RSA key . This pointer may be set to 0. +\return ::XND_ERROR_SUCCESS on success, an \ref xnodus_errors "error code" on failure, if the key contained in the object is not a private RSA key the function fails with error ::XLT_ERROR_INVALID_STATE. +\remark The unsigned integer pointed by 'p_key_len' receive the size of the key even if key_size is shorter and the function fails. +\see \ref xnd_key_data. +*/ +XND_LINK int XND_API xnd_keydata_get_as_formatted_rsa_xlt_priv_key(XND_KEY_DATA key_data, OUT unsigned char* key, unsigned int key_size, unsigned int* p_key_len); + +/** +\ingroup xnodus_crypto_key_man +Return the module length of the RSA key represented by a key data object +\param[in] key_data the handle of type ::XND_KEY_DATA which points to the key data object. +\return return the byte length of the module of the RSA key in the ::XND_KEY_DATA object. If the key is not RSA the value '0' (zero) is returned. +*/ +XND_LINK int XND_API xnd_keydata_get_rsa_mod_byte_len(XND_KEY_DATA key_data); + +/** +\ingroup xnodus_crypto_key_man +Return the key length of the formatted representation of the key contained int the object. +\param[in] key_data the handle of type ::XND_KEY_DATA which points to the key data object. +\return return the byte length of the formatter representation of the key in the ::XND_KEY_DATA object. On error the value '0' (zero) is returned. +*/ +XND_LINK int XND_API xnd_keydata_get_key_len(XND_KEY_DATA key_data); + +/** +\ingroup xnodus_crypto_key_man +Return the formatted key from a key data object. +\param[in] key_data the handle of type ::XND_KEY_DATA which points to the key data object. +\param[out] key points to a buffer that will receive the formatted key. +\param[in] key_size the size in bytes of the buffer pointed by 'key'. +\param[out] p_key_len points to an unsigned integer which will receive the length of the key . This pointer may be set to 0. +\return ::XND_ERROR_SUCCESS on success, an \ref xnodus_errors "error code" on failure. +\remark The unsigned integer pointed by 'p_key_len' receive the size of the key even if key_size is shorter and the function fails. +\see \ref xnd_key_data. +*/ +XND_LINK int XND_API xnd_keydata_get_as_formatted_key(XND_KEY_DATA key_data, OUT unsigned char* key, unsigned int key_size, unsigned int* p_key_len); + +/** +\ingroup xnodus_crypto_key_man +Return a string representing the key data object. +\param[in] key_data the handle of type ::XND_KEY_DATA which points to the key data object. +\param[in] wrap_key the wrap key object to be used to wrap the key. If this argument is set to '0' the returned string will be not encrypted. +\param[out] p_status points to an integer that will receive the status of the operation: ::XND_ERROR_SUCCESS on success, an \ref xnodus_errors "error code" on failure. +\return a string containing the base 64 encoding of the key data object. Use xnd_free() to free the allocated string. +\remark Free the memory pointed by the returned value using xnd_free(). +\see \ref xnd_key_data. +*/ +XND_LINK char* XND_API xnd_keydata_allocget_as_blob(XND_KEY_DATA key_data, OPT XND_KEY_DATA wrap_key, OPT OUT int * p_status); + +//////////////////////////////////////// + +//////////////////////////////////////// +//RSA functions + +//xnd_rsa_func + +/** +\ingroup xnd_rsa_func +Generate a new random private RSA key. +\param[in] env xNodus environment handle (see xnd_xlt_env_create()). +\param[in] key_bit_length length in bit of the desired RSA key. +\param[in] safe if not set to '0' compute a safe private key (it take a long time to complete). +\param[out] p_status points to an integer that will receive the status of the operation: ::XND_ERROR_SUCCESS on success, an \ref xnodus_errors "error code" on failure. +\return a ::XND_KEY_DATA handle which points to the allocated key data representing the RSA key. Use xnd_keydata_release() to release the returned object. +\see \ref xnd_key_data. +*/ +XND_LINK XND_KEY_DATA XND_API xnd_keydata_rsa_generate_private_create(XND_XLT_ENV env, unsigned int key_bit_length, unsigned int safe, OPT OUT int* p_status); + + + + + +//GET VALUES +//LEB = Little Endian Buffer +/** +\ingroup xnd_rsa_func +Return the modulus of an RSA key expressed as a \ref xnd_leb "little endian buffer". See \ref xnd_key_data. +\param[in] key_data the ::XND_KEY_DATA handle of a private or public RSA key. +\param[out] buffer points to the buffer that will receive the modulus value. +\param[in] buffer_size the size in bytes of the buffer pointed by the argument 'buffer'. +\param[out] p_buffer_len points to an unsigned integer that will receive the length in bytes of the modulus value. +\return ::XND_ERROR_SUCCESS on success, an \ref xnodus_errors "error code" on failure. +\note The value pointed by 'p_buffer_len' is set even if the buffer is null or the buffer size is not sufficient to receive the entire data. +*/ +XND_LINK int XND_API xnd_rsa_get_modulus_leb(XND_KEY_DATA key_data, OUT unsigned char* buffer, unsigned int buffer_size, OUT unsigned int* p_buffer_len); + +/** +\ingroup xnd_rsa_func +Return the public exponent of an RSA key expressed as a \ref xnd_leb "little endian buffer". See \ref xnd_key_data. +\param[in] key_data the ::XND_KEY_DATA handle of a private or public RSA key. +\param[out] buffer points to the buffer that will receive the public exponent value. +\param[in] buffer_size the size in bytes of the buffer pointed by the argument 'buffer'. +\param[out] p_buffer_len points to an unsigned integer that will receive the length in bytes of the public exponent value. +\return ::XND_ERROR_SUCCESS on success, an \ref xnodus_errors "error code" on failure. +\note The value pointed by 'p_buffer_len' is set even if the buffer is null or the buffer size is not sufficient to receive the entire data. +*/ +XND_LINK int XND_API xnd_rsa_get_pub_exp_leb(XND_KEY_DATA key_data, OUT unsigned char* buffer, unsigned int buffer_size, unsigned int* p_buffer_len); + +/** +\ingroup xnd_rsa_func +Return the prime number 'p' of a private RSA key expressed as a \ref xnd_leb "little endian buffer". See \ref xnd_key_data. +\param[in] key_data the ::XND_KEY_DATA handle of a private RSA key. +\param[out] buffer points to the buffer that will receive the prime number 'p' value. +\param[in] buffer_size the size in bytes of the buffer pointed by the argument 'buffer'. +\param[out] p_buffer_len points to an unsigned integer that will receive the length in bytes of the prime number 'p' value. +\return ::XND_ERROR_SUCCESS on success, an \ref xnodus_errors "error code" on failure. +\note The value pointed by 'p_buffer_len' is set even if the buffer is null or the buffer size is not sufficient to receive the entire data. +*/ +XND_LINK int XND_API xnd_rsa_get_p_leb(XND_KEY_DATA key_data, OUT unsigned char* buffer, unsigned int buffer_size, unsigned int* p_buffer_len); + +/** +\ingroup xnd_rsa_func +Return the prime number 'q' of a private RSA key expressed as a \ref xnd_leb "little endian buffer". See \ref xnd_key_data. +\param[in] key_data the ::XND_KEY_DATA handle of a private RSA key. +\param[out] buffer points to the buffer that will receive the prime number 'q' value. +\param[in] buffer_size the size in bytes of the buffer pointed by the argument 'buffer'. +\param[out] p_buffer_len points to an unsigned integer that will receive the length in bytes of the prime number 'q' value. +\return ::XND_ERROR_SUCCESS on success, an \ref xnodus_errors "error code" on failure. +\note The value pointed by 'p_buffer_len' is set even if the buffer is null or the buffer size is not sufficient to receive the entire data. +*/ +XND_LINK int XND_API xnd_rsa_get_q_leb(XND_KEY_DATA key_data, OUT unsigned char* buffer, unsigned int buffer_size, unsigned int* p_buffer_len); + +/** +\ingroup xnd_rsa_func +Return the 'dP' value (see \ref xnd_key_data) of a private RSA key expressed as a \ref xnd_leb "little endian buffer". +\param[in] key_data the ::XND_KEY_DATA handle of a private RSA key. +\param[out] buffer points to the buffer that will receive the 'dP' value. +\param[in] buffer_size the size in bytes of the buffer pointed by the argument 'buffer'. +\param[out] p_buffer_len points to an unsigned integer that will receive the length in bytes of the 'dP' value. +\return ::XND_ERROR_SUCCESS on success, an \ref xnodus_errors "error code" on failure. +\note The value pointed by 'p_buffer_len' is set even if the buffer is null or the buffer size is not sufficient to receive the entire data. +*/ +XND_LINK int XND_API xnd_rsa_get_dp_leb(XND_KEY_DATA key_data, OUT unsigned char* buffer, unsigned int buffer_size, unsigned int* p_buffer_len); + +/** +\ingroup xnd_rsa_func +Return the 'dQ' value (see \ref xnd_key_data) of a private RSA key expressed as a \ref xnd_leb "little endian buffer". +\param[in] key_data the ::XND_KEY_DATA handle of a private RSA key. +\param[out] buffer points to the buffer that will receive the 'dQ' value. +\param[in] buffer_size the size in bytes of the buffer pointed by the argument 'buffer'. +\param[out] p_buffer_len points to an unsigned integer that will receive the length in bytes of the 'dQ' value. +\return ::XND_ERROR_SUCCESS on success, an \ref xnodus_errors "error code" on failure. +\note The value pointed by 'p_buffer_len' is set even if the buffer is null or the buffer size is not sufficient to receive the entire data. +*/ +XND_LINK int XND_API xnd_rsa_get_dq_leb(XND_KEY_DATA key_data, OUT unsigned char* buffer, unsigned int buffer_size, unsigned int* p_buffer_len); + +/** +\ingroup xnd_rsa_func +Return the 'qInv' value of a private RSA key expressed as a \ref xnd_leb "little endian buffer". See \ref xnd_key_data. + +'qInv' is computed as follow: + +qInv = (1/q) mod p + +where 'p' and 'q' are the prime numbers of the RSA key. + +\param[in] key_data the ::XND_KEY_DATA handle of a private RSA key. +\param[out] buffer points to the buffer that will receive the 'qInv' value. +\param[in] buffer_size the size in bytes of the buffer pointed by the argument 'buffer'. +\param[out] p_buffer_len points to an unsigned integer that will receive the length in bytes of the 'qInv' value. +\return ::XND_ERROR_SUCCESS on success, an \ref xnodus_errors "error code" on failure. +\note The value pointed by 'p_buffer_len' is set even if the buffer is null or the buffer size is not sufficient to receive the entire data. +*/ +XND_LINK int XND_API xnd_rsa_get_qinv_leb(XND_KEY_DATA key_data, OUT unsigned char* buffer, unsigned int buffer_size, unsigned int* p_buffer_len); + +//CONVERT + +/** +\ingroup xnd_rsa_func +Convert a \ref xnd_leb "little endian buffer" expressing a big number to its decimal string representation. + +\param[in] env xNodus environment handle (see xnd_xlt_env_create()). +\param[in] num_buffer points to a buffer containing a little endian representation of a big number. +\param[in] num_buffer_len the length in bytes of the number pointed by num_buffer. +\param[out] str points to a buffer that will receive the base 10 representation string of the number. +\param[in] str_size the size of the buffer pointed by the 'str' argument. +\param[out] p_str_len points to an unsigned integer that will receive the length of the string number pointed by 'str'. +\return ::XND_ERROR_SUCCESS on success, an \ref xnodus_errors "error code" on failure. +\note The value pointed by 'p_str_len' is set even if 'num_buffer' is null or the string size is not enough to receive the entire data. +*/ +XND_LINK int XND_API xnd_rsa_convert_leb_to_bignum_string(XND_XLT_ENV env, const unsigned char* num_buffer, unsigned int num_buffer_len, OUT char* str, unsigned int str_size, OPT OUT unsigned int* p_str_len); +//only positive numbers + +/** +\ingroup xnd_rsa_func +Convert a decimal string representation of a positive big number to its \ref xnd_leb "little endian buffer" form. +\param[in] env xNodus environment handle (see xnd_xlt_env_create()). +\param[in] str_num points to a string containing the decimal representation of a positive big number. +\param[out] buffer points to a buffer that will receive the little endian representation of the passed big number. +\param[in] buffer_size the size in bytes of the buffer pointed by the 'buffer' argument. +\param[out] p_buffer_len points to an unsigned int that will contain the length in bytes of the little endian representation of the number. +\return ::XND_ERROR_SUCCESS on success, an \ref xnodus_errors "error code" on failure. +\note The value pointed by 'p_buffer_len' is set even if 'buffer' is null or the string size is not enough to receive the entire data. +*/ +XND_LINK int XND_API xnd_rsa_convert_bignum_string_to_leb(XND_XLT_ENV env, const char* str_num, OUT unsigned char* buffer, unsigned int buffer_size, OPT OUT unsigned int* p_buffer_len); + +//SET VALUES +/** +\ingroup xnd_rsa_func +Generate a ::XND_KEY_DATA object from the representation of the prime numbers and public exponenent of a private RSA key. +\param[in] env xNodus environment handle (see xnd_xlt_env_create()). +\param[in] p points to the buffer containing the \ref xnd_leb "little endian buffer" representation of the prime number 'p' of the RSA key. +\param[in] p_len the length in bytes of the representation of 'p'. +\param[in] q points to the buffer containing the \ref xnd_leb "little endian buffer" representation of the prime number 'q' of the RSA key. +\param[in] q_len the length in bytes of the representation of 'q'. +\param[in] e points to the buffer containing the \ref xnd_leb "little endian buffer" representation of the public exponenent of the RSA key. +\param[in] e_len the length in bytes of the representation of the public exponenent. +\param[out] p_status points to an integer that will receive the status of the operation: ::XND_ERROR_SUCCESS on success, an \ref xnodus_errors "error code" on failure. +\return a ::XND_KEY_DATA handle which points to the allocated key data object representing the private RSA key. +*/ +XND_LINK XND_KEY_DATA XND_API xnd_keydata_rsa_priv_key_create_from_pqe_leb(XND_XLT_ENV env, const unsigned char* p, unsigned int p_len, const unsigned char* q, unsigned int q_len, const unsigned char* e, unsigned int e_len, OPT OUT int* p_status); + +/** +\ingroup xnd_rsa_func +Generate a ::XND_KEY_DATA object from the representation of the modulus and public exponenent of a public RSA key. +\param[in] env xNodus environment handle (see xnd_xlt_env_create()). +\param[in] modulus points to the buffer containing the \ref xnd_leb "little endian buffer" representation of the modulus of the RSA key. +\param[in] modulus_len the length in bytes of the representation of the modulus. +\param[in] e points to the buffer containing the \ref xnd_leb "little endian buffer" representation of the public exponenent of the RSA key. +\param[in] e_len the length in bytes of the representation of the public exponenent. +\param[out] p_status points to an integer that will receive the status of the operation: ::XND_ERROR_SUCCESS on success, an \ref xnodus_errors "error code" on failure. +\return a ::XND_KEY_DATA handle which points to the allocated key data object representing the public RSA key. +*/ +XND_LINK XND_KEY_DATA XND_API xnd_keydata_rsa_pub_key_create_from_me_leb(XND_XLT_ENV env, const unsigned char* modulus, unsigned int modulus_len, const unsigned char* e, unsigned int e_len, OPT OUT int* p_status); + + +//ENCRIPTION (RAW encryption - no OAEP and PSS applied) +/** +\ingroup xnd_rsa_func +Perform RSA encryption +\remark Use this function just for testing purpose, don't use it in your protected application. +\param[in] key_data the ::XND_KEY_DATA handle of a public or private RSA key. +\param[in] plaintext points to a buffer containing the plaintext to be encrypted. +\param[in] plaintext_len the length of the plaintext (it must be equal to the modulus length in bytes of the RSA key). +\param[out] ciphertext points to a buffer that will receive the encrypted value. The length of the ciphertext will be the same of the plaintext. +\return ::XND_ERROR_SUCCESS on success, an \ref xnodus_errors "error code" on failure. +*/ +XND_LINK int XND_API xnd_rsa_raw_encrypt_leb(XND_KEY_DATA key_data, const unsigned char* plaintext, unsigned int plaintext_len, OUT unsigned char* ciphertext); + +/** +\ingroup xnd_rsa_func +Perform RSA decryption +\remark Use this function just for testing purpose, don't use it in your protected application. +\param[in] key_data the ::XND_KEY_DATA handle of a private RSA key. +\param[in] ciphertext points to a buffer containing the ciphertext to be decrypted. +\param[in] ciphertext_len the length of the ciphertext (it must be equal to the modulus length in bytes of the RSA key). +\param[out] ret_plaintext points to a buffer that will receive the decrypted value. The length of the decrypted value will be the same of the ciphertext. +\return ::XND_ERROR_SUCCESS on success, an \ref xnodus_errors "error code" on failure. +*/ +XND_LINK int XND_API xnd_rsa_raw_decrypt_leb(XND_KEY_DATA key_data, const unsigned char* ciphertext, unsigned int ciphertext_len, OUT unsigned char* ret_plaintext); + +//calc the module respect the key +//let 'M' be the modulus of the RSA key in the __XND_KEY_DATA: this functioncompute the residue module 'M' of the little endian buffer number of ret_value +/** +\ingroup xnd_rsa_func +Compute the residue module 'm' of a number expressed in \ref xnd_leb "little endian buffer" form where 'm' is the modulus of an RSA key. +\remark Use this function just for testing purpose, don't use it in your protected application. +\param[in] key_data the ::XND_KEY_DATA handle of a private or public RSA key where the modulus is extracted. +\param[in] value points to a buffer containing the number expressed in \ref xnd_leb "little endian buffer" form from which the residue module 'm' must be computed. +\param[in] value_len length of the number representation pointed by the argument 'value'. +\param[out] ret_value points to a buffer that will receive the computed residue expressed in \ref xnd_leb "little endian buffer" form. +\param[in] ret_value_size the size in bytes of the buffer pointed by 'ret_value'. +\param[out] p_ret_value_len points to an integer that will receive the length of the returned residue value. +\return ::XND_ERROR_SUCCESS on success, an \ref xnodus_errors "error code" on failure. +*/ +XND_LINK int XND_API xnd_rsa_calc_mod_key_leb(XND_KEY_DATA key_data, const unsigned char* value, unsigned int value_len, OUT unsigned char* ret_value, unsigned int ret_value_size, OPT OUT unsigned int* p_ret_value_len); + + +/** +\ingroup xnodus_misc +Free a buffer or a string allocated by xNodus API functions +\param[in] p points to the buffer to free. +*/ +XND_LINK void XND_API xnd_free(void* p); + +//\cond NOT_COMMENTED +XND_LINK unsigned char* XND_API xnd_keydata_to_bytes_alloc(XND_KEY_DATA ctx, OPT OUT unsigned int* p_len); +XND_LINK XND_KEY_DATA XND_API xnd_keydata_from_bytes_create(const unsigned char* data, unsigned int data_len); +//\endcond + +/** +\ingroup xnodus_misc +Generate a pseudo random value. +\remark Use this function just for testing purpose, don't use it in your protected application. +\param[in] env xNodus environment handle (see xnd_xlt_env_create()). +\param[out] buffer points to a buffer that will receive the pseudo random value. +\param[in] buffer_len the length in bytes of the random buffer to be returned. This length cannot be greater than the size of the buffer to be filled. +\return ::XND_ERROR_SUCCESS on success, an \ref xnodus_errors "error code" on failure. +*/ +XND_LINK int XND_API xnd_rand(XND_XLT_ENV env, OUT unsigned char* buffer, unsigned int buffer_len); + + + +/** +\ingroup xnd_user_data_group +Return a pointer to a string containing the encoded form of the data related to a user (see \ref xnd_user_data). + +\param[in] env xNodus environment handle (see xnd_xlt_env_create()). +\param[in] key_data the ::XND_KEY_DATA handle of an object containing a private or secret key. +\param[in] user_name points to a ::XND_USER_NAME structure containing the type and name of a user. +\param[in] wrap_key the ::XND_KEY_DATA handle of an object containing a secret key (AES) used to wrap the returned values. This argument may be set to 0 and no wrapping will be done +\param[out] p_status points to an integer that will receive the status of the operation: ::XND_ERROR_SUCCESS on success, an \ref xnodus_errors "error code" on failure. +\return return the string containing the encoded form of the data related to the user and its key. +\remark Free the memory pointed by the returned value using xnd_free(). +*/ +XND_LINK char* XND_API xnd_allocget_user_data(XND_XLT_ENV env, XND_KEY_DATA key_data, const XND_USER_NAME* user_name, OPT XND_KEY_DATA wrap_key, OPT OUT int* p_status); + +/** +\ingroup xnd_user_data_group +Extract the user name from a user data string (see \ref xnd_user_data). + +\param[in] env xNodus environment handle (see xnd_xlt_env_create()). +\param[in] user_data points to the user data string. +\param[in] wrap_key the ::XND_KEY_DATA handle of an object containing a secret key (AES) used to unwrap the user data string. If the passed string is not encrypted this entry must be set to 0. +\param[out] user_name points to a ::XND_USER_NAME structure that will contain the type and username of the user. +\return ::XND_ERROR_SUCCESS on success, an \ref xnodus_errors "error code" on failure. +\see xnd_allocget_user_data() +*/ +XND_LINK int XND_API xnd_get_user_name_from_user_data_blob(XND_XLT_ENV env, const char* user_data, OPT XND_KEY_DATA wrap_key, OUT P_XND_USER_NAME user_name); + +/** +\ingroup xnd_user_data_group +Create a ::XND_KEY_DATA object of the cryptographic key encoded in a user data string (see \ref xnd_user_data). + +\param[in] env xNodus environment handle (see xnd_xlt_env_create()). +\param[in] user_data points to the user data string. +\param[in] wrap_key the ::XND_KEY_DATA handle of an object containing a secret key (AES) used to unwrap the user data string. If the passed string is not encrypted this entry must be set to 0. +\param[out] p_status points to an integer that will receive the status of the operation: ::XND_ERROR_SUCCESS on success, an \ref xnodus_errors "error code" on failure. +\return a ::XND_KEY_DATA handle which points to the allocated key data object representing the key contained in the user data string. +\remark Free the ::XND_KEY_DATA returned by this function with xnd_keydata_release(). +*/ +XND_LINK XND_KEY_DATA XND_API xnd_create_keydata_from_user_data_blob(XND_XLT_ENV env, const char* user_data, OPT XND_KEY_DATA wrap_key, OPT OUT int* p_status); + + +/** +\ingroup xnd_devctx_data +Create a ::XND_DEVICE_CONTEXT_DATA object (see \ref xnd_devctx_by_index). +\param[in] env xNodus environment handle (see xnd_xlt_env_create()). +\return an handle which refers to a newly created ::XND_DEVICE_CONTEXT_DATA object. +*/ +XND_LINK XND_DEVICE_CONTEXT_DATA XND_API xnd_xlt_devctx_data_create(XND_XLT_ENV env); + +/** +\ingroup xnd_devctx_data +Release a device context data object pointed by a ::XND_DEVICE_CONTEXT_DATA handle (see \ref xnd_create_acquire_release). +\param[in] device_context_data the ::XND_DEVICE_CONTEXT_DATA handle referencing to the object to release. +\return ::XND_ERROR_SUCCESS on success, an \ref xnodus_errors "error code" on failure, and ::XND_RELEASE_STILL_REFERENCED if there are still reference to the object. +\see \ref xnd_devctx_by_index, xnd_xlt_devctx_data_create(). +*/ +XND_LINK int XND_API xnd_xlt_devctx_data_release(XND_DEVICE_CONTEXT_DATA device_context_data); + +/** +\ingroup xnd_devctx_data +Acquire a device context data object pointed by a ::XND_DEVICE_CONTEXT_DATA handle (see \ref xnd_create_acquire_release). +\param[in] device_context_data the ::XND_DEVICE_CONTEXT_DATA handle referencing to the object to acquire. +\return on success a reference to the input ::XND_NET_DATA handle, '0' otherwise. +\remark The reference to the ::XND_DEVICE_CONTEXT_DATA handle obtained by this function must be freed calling xnd_xlt_devctx_data_release(). +\see \ref xnd_devctx_by_index, xnd_xlt_devctx_data_create(). +*/ +XND_LINK XND_DEVICE_CONTEXT_DATA XND_API xnd_xlt_devctx_data_acquire(XND_DEVICE_CONTEXT_DATA device_context_data); + +/** +\ingroup xnd_devctx_data +Add an xNodus device context description to a ::XND_DEVICE_CONTEXT_DATA object (see \ref xnd_devctx_by_index). +\param[in] device_context_data an handle that refers to a ::XND_DEVICE_CONTEXT_DATA object to which add an xNodus device context description. +\param[in] addr_port a string representing a net address and port to be used to connect to the described xNodus device. +\param[in] xnodus_key_blob points to a string representation of the public key of the xNodus device to be contacted. +\param[in] user_data_blob points to a string encoding the user data (see \ref xnd_user_data_group). This entry may be set to 0 if an 'Anonymous' user is used (see \ref xnd_users_types). +\param[in] user_data_wrap_key_string points to a string representation of a wrap key used to unwrap the 'user_data_blob' entry. If 'user_data_blob' is set to '0' or not encrypted this entry must be set to '0'. +\param[in] keep_alive_sec establish the 'keep alive' period in seconds of the sessions that can be open on the xNodus device (see \ref xnd_keep_alive). If the value is set to '0' the default value is taken (60 seconds). +\param[in] recv_to_msec the maximum time in millisecond that the client wait for an answer from the xNodus device. +\return ::XND_ERROR_SUCCESS on success, an \ref xnodus_errors "error code" on failure. +\remark At present the entry 'addr_port' can be a string representing an IPv4 address plus a port (for example 192.168.0.123:15678) or an URL plus the port (for example xnddevice.yourdomain.com:15678). +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". +\see xnd_xlt_add_xnodus_to_devctx_data2(), xnd_xlt_add_xnodus_to_devctx_data3(). +*/ +XND_LINK int XND_API xnd_xlt_add_xnodus_to_devctx_data(XND_DEVICE_CONTEXT_DATA device_context_data, const char* addr_port, const char* xnodus_key_blob, OPT const char* user_data_blob, OPT const char* user_data_wrap_key_string, OPT unsigned int keep_alive_sec, OPT unsigned int recv_to_msec); + +/** +\ingroup xnd_devctx_data +Add an xNodus device context description to a ::XND_DEVICE_CONTEXT_DATA object (see \ref xnd_devctx_by_index). +This function performs the same task of xnd_xlt_add_xnodus_to_devctx_data() with arguments passed in different formats. +\param[in] device_context_data an handle that refers to a ::XND_DEVICE_CONTEXT_DATA object to which add an xNodus device context description. +\param[in] xnd_net_data handle that refers to a ::XND_NET_DATA object containing the network connection information that must be used connecting the xNodus device. +\param[in] xnodus_key_blob points to a string representation of the public key of the xNodus device to be contacted. +\param[in] user_data_blob points to a string encoding the user data (see \ref xnd_user_data_group). This entry may be set to 0 if an 'Anonymous' user is used (see \ref xnd_users_types). +\param[in] user_data_wrap_key a handle referring to a :: XND_KEY_DATA object representing the wrap key used to unwrap the 'user_data_blob' entry. If 'user_data_blob' is set to '0' or not encrypted this entry must be set to '0'. +\param[in] keep_alive_sec establish the 'keep alive' period in seconds of the sessions that can be open on the xNodus device (see \ref xnd_keep_alive). If the value is set to '0' the default value is taken (60 seconds). +\return ::XND_ERROR_SUCCESS on success, an \ref xnodus_errors "error code" on failure. +\see xnd_xlt_add_xnodus_to_devctx_data(), xnd_xlt_add_xnodus_to_devctx_data3(). +*/ +XND_LINK int XND_API xnd_xlt_add_xnodus_to_devctx_data2(XND_DEVICE_CONTEXT_DATA device_context_data, XND_NET_DATA xnd_net_data, const char* xnodus_key_blob, OPT const char* user_data_blob, OPT XND_KEY_DATA user_data_wrap_key, OPT unsigned int keep_alive_sec); + +/** +\ingroup xnd_devctx_data +Add an xNodus device context description to a ::XND_DEVICE_CONTEXT_DATA object (see \ref xnd_devctx_by_index). +This function performs the same task of xnd_xlt_add_xnodus_to_devctx_data() with arguments passed in different formats. +\param[in] device_context_data an handle that refers to a ::XND_DEVICE_CONTEXT_DATA object to which add an xNodus device context description. +\param[in] xnd_net_data handle that refers to a ::XND_NET_DATA object containing the network connection information that must be used connecting the xNodus device. +\param[in] xnodus_key_data handle of a ::XND_KEY_DATA object referring to the public key of the xNodus device. +\param[in] user_name points to a ::XND_USER_NAME structure containing the name of the user that will connect to the xNodus device. +\param[in] user_key_data handle of a ::XND_KEY_DATA object referring to the private (or secret) key related to the user referred by 'user_name' entry. +\param[in] keep_alive_sec establish the 'keep alive' period in seconds of the sessions that can be open on the xNodus device (see \ref xnd_keep_alive). If the value is set to '0' the default value is taken (60 seconds). +\return ::XND_ERROR_SUCCESS on success, an \ref xnodus_errors "error code" on failure. +\see xnd_xlt_add_xnodus_to_devctx_data(), xnd_xlt_add_xnodus_to_devctx_data2(). +*/ +XND_LINK int XND_API xnd_xlt_add_xnodus_to_devctx_data3(XND_DEVICE_CONTEXT_DATA device_context_data, XND_NET_DATA xnd_net_data, XND_KEY_DATA xnodus_key_data, OPT const XND_USER_NAME* user_name, OPT XND_KEY_DATA user_key_data, OPT unsigned int keep_alive_sec); + +/** +\ingroup xnd_devctx_data +Add an xNodus device context description to a ::XND_DEVICE_CONTEXT_DATA object (see \ref xnd_devctx_by_index). +\param[in] device_context_data an handle that refers to a ::XND_DEVICE_CONTEXT_DATA object to which add an xNodus device context description. +\param[in] addr_port a string representing a net address and port to be used to connect to the described xNodus device. +\param[in] xnodus_key_blob points to a string representation of the public key of the xNodus device to be contacted. +\param[in] user_data_blob points to a string encoding the user data (see \ref xnd_user_data_group). This entry may be set to 0 if an 'Anonymous' user is used (see \ref xnd_users_types). +\param[in] user_data_wrap_key_string points to a string representation of a wrap key used to unwrap the 'user_data_blob' entry. If 'user_data_blob' is set to '0' or not encrypted this entry must be set to '0'. +\param[in] net_protocol indicates the protocol to be used. At present TCP and UDP are supported (see \ref xnd_protocol_type to specify the desired protocol). By setting this entry to zero the TCP protocol is used. +\param[in] keep_alive_sec establish the 'keep alive' period in seconds of the sessions that can be open on the xNodus device (see \ref xnd_keep_alive). If the value is set to '0' the default value is taken (60 seconds). +\param[in] recv_to_msec the maximum time in millisecond that the client wait for an answer from the xNodus device. +\return ::XND_ERROR_SUCCESS on success, an \ref xnodus_errors "error code" on failure. +\remark At present the entry 'addr_port' can be a string representing an IPv4 address plus a port (for example 192.168.0.123:15678) or an URL plus the port (for example xnddevice.yourdomain.com:15678). +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". +\see xnd_xlt_add_xnodus_to_devctx_data2(), xnd_xlt_add_xnodus_to_devctx_data3(). +*/ +XND_LINK int XND_API xnd_xlt_add_xnodus_to_devctx_data4(XND_DEVICE_CONTEXT_DATA device_context_data, const char* addr_port, const char* xnodus_key_blob, OPT const char* user_data_blob, OPT const char* user_data_wrap_key_string, OPT unsigned int net_protocol, OPT unsigned int keep_alive_sec, OPT unsigned int recv_to_msec); + + +/** +\ingroup xnd_devctx_data +Add an XLight connection description to a ::XND_DEVICE_CONTEXT_DATA object (see \ref xnd_devctx_by_index). +\param[in] device_context_data an handle that refers to a ::XND_DEVICE_CONTEXT_DATA object to which add an xNodus device context description. +\param[in] password the password of the XLight device (the one set by the function xnd_xlt_setup()). +\return ::XND_ERROR_SUCCESS on success, an \ref xnodus_errors "error code" on failure. +*/ +XND_LINK int XND_API xnd_xlt_add_xlight_to_devctx_data(XND_DEVICE_CONTEXT_DATA device_context_data, OPT const unsigned char* password); + +//\cond NOT_COMMENTED +XND_LINK unsigned char* XND_API xnd_xlt_devctx_data_to_bytes_alloc(XND_DEVICE_CONTEXT_DATA device_context_data, unsigned int* p_len); +XND_LINK XND_DEVICE_CONTEXT_DATA XND_API xnd_xlt_devctx_data_from_bytes_create(XND_XLT_ENV env, const unsigned char* data, unsigned int data_len); +//\endcond + + +/** +\defgroup xnd_devctx_flags Device context flags +\ingroup xnodus_defines + +The bitwise 'OR' operation of a subset of the following values defines feature of the created device context +@{ +*/ +#define XND_XLT_DEVCTX_FLAG_XNODUS_AUTO_OPEN 0x1 ///< before sending any command to the device the session is open if not already running +#define XND_XLT_DEVCTX_FLAG_XNODUS_MANUAL_KEEP_ALIVE 0x2 ///< the keep alive (see \ref xnd_keep_alive) procedure must not be managed by the APIs +#define XND_XLT_DEVCTX_FLAG_XNODUS_AUTO_REOPEN_SESSION 0x4 ///< the APIs re-open automatically a session after a communication error (after a communication error it is very likely that client and xNodus device lose their synchronization and then lose the possibility to continue the current session) +#define XND_XLT_DEVCTX_FLAG_XNODUS_MULTI_INSTANCE 0x8 ///< multiple sessions opened by different instances of the protected application running onto a single PC consume only one license (see \ref xnd_users_group_lic). +#define XND_XLT_DEVCTX_FLAG_XLIGHT_NO_AUTO_CLOSE_SESSION 0x10 ///< On Xlight never close implicitly an open session (useful if used in multithreading). Without this setting xnd_module_devctx_release() close the session if not already done. +//@} //xnd_devctx_flags + +//\ingroup xnodus_main_functions +/** +\ingroup xnd_devctx +Create an xNodus device context (see \ref xnd_device_context for an introduction on device contexts and \ref xnd_create_devctx_explicit). +\param[in] env xNodus environment handle (see xnd_xlt_env_create()). +\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. If this entry is set to '0' an anonymous user is used. +\param[in] user_data_wrap_key_string points to the string containing the key to unwrap 'user_data_blob'. This parameter can be set to '0' if the 'user_data_blob' argument is not encrypted (or not present). +\param[in] flags flags value obtained by the logical 'OR' of the mask values \ref xnd_devctx_flags. +\param[in] keep_alive_sec keep alive time for a session opened on this device context (see \ref xnd_keep_alive). If set to zero the default value is taken (60 seconds). +\param[in] recv_to_msec maximum time to get an answer from the connected xNodus. If set to zero the default value is taken (5 seconds). +\param[out] p_status points to an integer that will receive the status of the operation: ::XND_ERROR_SUCCESS on success, an \ref xnodus_errors "error code" on failure. +\return a ::XND_DEVICE_CONTEXT handle referring to the created device context object. +\parblock +\remark The argument 'addr_port' is a string of the form \.\, for instance: 192.168.0.125:15678 or foo.example.com:15678. +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". +\endparblock +\parblock +\remark The returned ::XND_DEVICE_CONTEXT handle must be released calling xnd_xlt_devctx_release(). +\endparblock +\see xnd_xlt_devctx_xnodus_create2(), xnd_xlt_devctx_xnodus_create3(). +*/ +XND_LINK XND_DEVICE_CONTEXT XND_API xnd_xlt_devctx_xnodus_create(XND_XLT_ENV env, const char* addr_port, const char* xnodus_key_blob, OPT const char* user_data_blob, OPT const char* user_data_wrap_key_string, OPT unsigned int flags, OPT unsigned int keep_alive_sec, OPT unsigned int recv_to_msec, OPT OUT int* p_status); + +/** +\ingroup xnd_devctx +Create an xNodus device context (see \ref xnd_device_context for an introduction on device contexts and \ref xnd_create_devctx_explicit). + +This function is similar to xnd_xlt_devctx_xnodus_create() and only differs for the different argumet type passed. +\param[in] env xNodus environment handle (see xnd_xlt_env_create()). +\param[in] xnd_net_data a ::XND_NET_DATA handle referring to the phisical address of the xNodus device. +\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. If this entry is set to '0' an anonymous user is used. +\param[in] user_data_wrap_key a handle referring to a :: XND_KEY_DATA object representing the wrap key used to unwrap the 'user_data_blob' entry. If 'user_data_blob' is set to '0' or not encrypted this entry must be set to '0'. +\param[in] flags flags value obtained by the logical 'OR' of the mask values \ref xnd_devctx_flags. +\param[in] keep_alive_sec keep alive time for a session opened on this device context (see \ref xnd_keep_alive). If set to zero the default value is taken (60 seconds). +\param[out] p_status points to an integer that will receive the status of the operation: ::XND_ERROR_SUCCESS on success, an \ref xnodus_errors "error code" on failure. +\return a ::XND_DEVICE_CONTEXT handle referring to the created device context object. +\parblock +\remark The returned ::XND_DEVICE_CONTEXT handle must be released calling xnd_xlt_devctx_release(). +\endparblock +\see xnd_xlt_devctx_xnodus_create(), xnd_xlt_devctx_xnodus_create3(). +*/ +XND_LINK XND_DEVICE_CONTEXT XND_API xnd_xlt_devctx_xnodus_create2(XND_XLT_ENV env, XND_NET_DATA xnd_net_data, const char* xnodus_key_blob, OPT const char* user_data_blob, OPT XND_KEY_DATA user_data_wrap_key, OPT unsigned int flags, OPT unsigned int keep_alive_sec, OPT OUT int* p_status); + +/** +\ingroup xnd_devctx +Create an xNodus device context (see \ref xnd_device_context for an introduction on device contexts and \ref xnd_create_devctx_explicit). + +This function is similar to xnd_xlt_devctx_xnodus_create() and only differs for the different argumet type passed. +\param[in] env xNodus environment handle (see xnd_xlt_env_create()). +\param[in] xnd_net_data a ::XND_NET_DATA handle referring to the phisical address of the xNodus device. +\param[in] xnodus_key_data handle of a ::XND_KEY_DATA object referring to the public key of the xNodus device. +\param[in] user_name points to a ::XND_USER_NAME structure containing the name of the user that will connect to the xNodus device. If this entry is set to '0' an anonymous user is used. +\param[in] user_key_data handle of a ::XND_KEY_DATA object referring to the private (or secret) key related to the user referred by 'user_name' entry. If 'user_name' refers to an anonymous user this entry must be set to '0'. +\param[in] flags flags value obtained by the logical 'OR' of the mask values \ref xnd_devctx_flags. +\param[in] keep_alive_sec keep alive time for a session opened on this device context (see \ref xnd_keep_alive). If set to zero the default value is taken (60 seconds). +\param[out] p_status points to an integer that will receive the status of the operation: ::XND_ERROR_SUCCESS on success, an \ref xnodus_errors "error code" on failure. +\return a ::XND_DEVICE_CONTEXT handle referring to the created device context object. +\parblock +\remark The returned ::XND_DEVICE_CONTEXT handle must be released calling xnd_xlt_devctx_release(). +\endparblock +\see xnd_xlt_devctx_xnodus_create(), xnd_xlt_devctx_xnodus_create2(). +*/ +XND_LINK XND_DEVICE_CONTEXT XND_API xnd_xlt_devctx_xnodus_create3(XND_XLT_ENV env, XND_NET_DATA xnd_net_data, XND_KEY_DATA xnodus_key_data, OPT const XND_USER_NAME* user_name, OPT XND_KEY_DATA user_key_data, OPT unsigned int flags, OPT unsigned int keep_alive_sec, OPT OUT int* p_status); + +/** +\ingroup xnd_devctx +Create an xNodus device context (see \ref xnd_device_context for an introduction on device contexts and \ref xnd_create_devctx_explicit). +\param[in] env xNodus environment handle (see xnd_xlt_env_create()). +\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. If this entry is set to '0' an anonymous user is used. +\param[in] user_data_wrap_key_string points to the string containing the key to unwrap 'user_data_blob'. This parameter can be set to '0' if the 'user_data_blob' argument is not encrypted (or not present). +\param[in] flags flags value obtained by the logical 'OR' of the mask values \ref xnd_devctx_flags. +\param[in] net_protocol indicates the protocol to be used. At present TCP and UDP are supported (see \ref xnd_protocol_type to specify the desired protocol). By setting this entry to zero the TCP protocol is used. +\param[in] keep_alive_sec keep alive time for a session opened on this device context (see \ref xnd_keep_alive). If set to zero the default value is taken (60 seconds). +\param[in] recv_to_msec maximum time to get an answer from the connected xNodus. If set to zero the default value is taken (5 seconds). +\param[out] p_status points to an integer that will receive the status of the operation: ::XND_ERROR_SUCCESS on success, an \ref xnodus_errors "error code" on failure. +\return a ::XND_DEVICE_CONTEXT handle referring to the created device context object. +\parblock +\remark The argument 'addr_port' is a string of the form \.\, for instance: 192.168.0.125:15678 or foo.example.com:15678. +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". +\endparblock +\parblock +\remark The returned ::XND_DEVICE_CONTEXT handle must be released calling xnd_xlt_devctx_release(). +\endparblock +\see xnd_xlt_devctx_xnodus_create2(), xnd_xlt_devctx_xnodus_create3(). +*/ +XND_LINK XND_DEVICE_CONTEXT XND_API xnd_xlt_devctx_xnodus_create4(XND_XLT_ENV env, const char* addr_port, const char* xnodus_key_blob, OPT const char* user_data_blob, OPT const char* user_data_wrap_key_string, OPT unsigned int flags, OPT unsigned int net_protocol, OPT unsigned int keep_alive_sec, OPT unsigned int recv_to_msec, OPT OUT int* p_status); + +//\ingroup xnodus_main_functions +/** +\ingroup xnd_devctx +Create an XLight device context (see \ref xnd_device_context for an introduction on device contexts). + +This function is analogous to xnd_xlt_devctx_xnodus_create() but here the device context refer to an XLight device rather then xNodus. +\param[in] env xNodus environment handle (see xnd_xlt_env_create()). +\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] password points to a buffer of length ::XLT_PASSWORD_SIZE. It contains the password to be assigned to the device. This entry may be set to '0'. +\param[in] flags flags value obtained by the logical 'OR' of the mask values \ref xnd_devctx_flags. +\param[out] p_status points to an integer that will receive the status of the operation: ::XND_ERROR_SUCCESS on success, an \ref xnodus_errors "error code" on failure. +\return a ::XND_DEVICE_CONTEXT handle referring to the created device context object. +\remark The returned ::XND_DEVICE_CONTEXT handle must be released calling xnd_xlt_devctx_release(). +*/ +XND_LINK XND_DEVICE_CONTEXT XND_API xnd_xlt_devctx_xlight_create(XND_XLT_ENV env, unsigned int device, OPT const unsigned char* password, OPT unsigned int flags, OPT OUT int* p_status); + +#define XNODUS_DEVICE_BASE_INDEX XLT_DEVICE_MAX ///< starting device address for xNodus device when using xnd_xlt_devctx_create(). Lower device values refer to XLight + +/** +\ingroup xnd_devctx +Create an xNodus or XLight device context (see \ref xnd_device_context for an introduction on device contexts and \ref xnd_devctx_by_index). +\param[in] device_context_data handle of an object of type ::XND_DEVICE_CONTEXT_DATA collecting the set of xNodus and XLight description of managed devices. +\param[in] device the index of the device on which create the device context. +\param[in] flags flags value obtained by the logical 'OR' of the mask values \ref xnd_devctx_flags. +\param[out] p_status points to an integer that will receive the status of the operation: ::XND_ERROR_SUCCESS on success, an \ref xnodus_errors "error code" on failure. +\return a ::XND_DEVICE_CONTEXT handle referring to the created device context object. +\remark if the argument 'device' runs from 0 to ::XLT_DEVICE_MAX -1 an XLight is instance is created, while for values equal or greater than ::XLT_DEVICE_MAX +an xNodus instance is created. +*/ +XND_LINK XND_DEVICE_CONTEXT XND_API xnd_xlt_devctx_create(XND_DEVICE_CONTEXT_DATA device_context_data, unsigned int device, OPT unsigned int flags, OPT OUT int* p_status); + +//\ingroup xnodus_main_functions +/** +\ingroup xnd_devctx +Release a device context object pointed by a ::XND_DEVICE_CONTEXT handle (see \ref xnd_create_acquire_release). +\param[in] dev_ctx the ::XND_DEVICE_CONTEXT handle referencing to the object to release. +\return ::XND_ERROR_SUCCESS on success, an \ref xnodus_errors "error code" on failure, and ::XND_RELEASE_STILL_REFERENCED if there are still reference to the object. +*/ +XND_LINK int XND_API xnd_xlt_devctx_release(XND_DEVICE_CONTEXT dev_ctx); + +/** +\ingroup xnd_devctx +Acquire a device context object pointed by a ::XND_DEVICE_CONTEXT handle (see \ref xnd_create_acquire_release). +\param[in] dev_ctx a ::XND_DEVICE_CONTEXT handle referencing the object to acquire. +\return on success a reference to the input ::XND_DEVICE_CONTEXT handle, '0' otherwise. +\remark The reference to the ::XND_DEVICE_CONTEXT handle obtained by this function must be freed calling xnd_xlt_devctx_release(). +*/ +XND_LINK XND_DEVICE_CONTEXT XND_API xnd_xlt_devctx_acquire(XND_DEVICE_CONTEXT dev_ctx); + +/** +\ingroup xnd_devctx +Return the device index of the device context. +\param[in] dev_ctx a ::XND_DEVICE_CONTEXT handle referring to the device context object. +\return return the index value of the device context. +\remark If the device context was created on an XLight dongle the returned value runs from 0 to ::XLT_DEVICE_MAX - 1, if the device context was created using xnd_xlt_devctx_create() on an xNodus device +the returned value is a value equal or grater than ::XLT_DEVICE_MAX, and finally if the device context was created with xnd_xlt_devctx_xnodus_create(), xnd_xlt_devctx_xnodus_create2() or xnd_xlt_devctx_xnodus_create3() the +returned value is always ::XLT_DEVICE_MAX. +*/ +XND_LINK unsigned int XND_API xnd_xlt_devctx_get_device_index(XND_DEVICE_CONTEXT dev_ctx); + +//\ingroup xnodus_main_functions +/** +\ingroup xnd_session +Open the session of a device context (See \ref xnd_session). +\param[in] dev_ctx a ::XND_DEVICE_CONTEXT handle referring to the device context object. +\param[in] wrap_key_or_password points to a buffer of length 32 bytes containing an XLight password or a wrap key for an xNodus user data string(see \ref xnd_deferring_wrap_key). +\return ::XND_ERROR_SUCCESS on success, an \ref xnodus_errors "error code" on failure. +\see xnd_xlt_session_open2(), xnd_xlt_session_open3() +*/ +XND_LINK int XND_API xnd_xlt_session_open(XND_DEVICE_CONTEXT dev_ctx, OPT const unsigned char* wrap_key_or_password); + +/** +\ingroup xnd_session +Open the session of a device context (See \ref xnd_session). +\param[in] dev_ctx a ::XND_DEVICE_CONTEXT handle referring to the device context object. +\param[in] wrap_key_string points to an xNodus wrap key string of an xNodus user data blob string (see \ref xnd_deferring_wrap_key). +\return ::XND_ERROR_SUCCESS on success, an \ref xnodus_errors "error code" on failure. +\remark With this function it is not possible to open a device context on an XLight device unless the 'wrap_key_string' entry is set to zero. +\see xnd_xlt_session_open(), xnd_xlt_session_open3() +*/ +XND_LINK int XND_API xnd_xlt_session_open2(XND_DEVICE_CONTEXT dev_ctx, OPT const char* wrap_key_string); + +/** +\ingroup xnd_session +Open the session of a device context (See \ref xnd_session). +\param[in] dev_ctx a ::XND_DEVICE_CONTEXT handle referring to the device context object. +\param[in] wrap_key handle of a ::XND_KEY_DATA object referring to the wrap key of an xNodus user data blob string (see \ref xnd_deferring_wrap_key). +\return ::XND_ERROR_SUCCESS on success, an \ref xnodus_errors "error code" on failure. +\remark With this function it is not possible to open a device context on an XLight device unless the 'wrap_key' entry is set to zero. +\see xnd_xlt_session_open(), xnd_xlt_session_open2() +*/ +XND_LINK int XND_API xnd_xlt_session_open3(XND_DEVICE_CONTEXT dev_ctx, OPT XND_KEY_DATA wrap_key); + +//\ingroup xnodus_main_functions +/** +\ingroup xnd_session +Close the session of a device context (See \ref xnd_session). +\param[in] dev_ctx a ::XND_DEVICE_CONTEXT handle referring to the device context object. +\return ::XND_ERROR_SUCCESS on success, an \ref xnodus_errors "error code" on failure. +*/ +XND_LINK int XND_API xnd_xlt_session_close(XND_DEVICE_CONTEXT dev_ctx); + +/** +\ingroup xnd_session +Send a manual keep alive command to the device (see \ref xnd_keep_alive). +\param[in] dev_ctx a ::XND_DEVICE_CONTEXT handle referring to the device context object. +\return ::XND_ERROR_SUCCESS on success, an \ref xnodus_errors "error code" on failure. +\remark This function must be called only when the session is open. +*/ +XND_LINK int XND_API xnd_xlt_session_keep_alive(XND_DEVICE_CONTEXT dev_ctx); + +////////////////////////////////////////// +//device context types +/** +\defgroup xnd_devctx_type Device context Type +\ingroup xnodus_defines +These are the possible device context type values. These value are related to the hardware of the connected device that can be an xNodus or an XLight. +@{ +*/ +#define XND_DEVICE_CONTEXT_TYPE_UNKNOWN 0 ///< unknown device +#define XND_DEVICE_CONTEXT_TYPE_XLIGHT 1 ///< XLight device attached +#define XND_DEVICE_CONTEXT_TYPE_XNODUS 2 ///< xNodus device attached +//@} //xnd_devctx_type + +/** +\ingroup xnd_devctx +Return the type of the device related to the current device context +\param dev_ctx the device context handle +\return a value from \ref xnd_devctx_type. +*/ +XND_LINK unsigned int XND_API xnd_xlt_get_devctx_type(XND_DEVICE_CONTEXT dev_ctx); + +/** +\ingroup xnd_session +Check whether a device context is in open session state or not +\param[in] dev_ctx a ::XND_DEVICE_CONTEXT handle referring to the device context object. +\return non zero if the device context is open, return 0 if not open or an error occurred. +*/ +XND_LINK int XND_API xnd_xlt_is_session_open(XND_DEVICE_CONTEXT dev_ctx); + + +//xnodus_modules +/** +\ingroup xnodus_modules +Create a device context referring a given module (see \ref xnd_modules). +\param[in] dev_ctx a ::XND_DEVICE_CONTEXT handle referring to the device context object. +\param[in] module_index the index of the module to be opened. This value must be equal or grater than '0' and less than ::XND_MAX_NUM_MODULES. +\param[out] p_status points to an integer that will receive the status of the operation: ::XND_ERROR_SUCCESS on success, an \ref xnodus_errors "error code" on failure. +\return a ::XND_DEVICE_CONTEXT handle referring to the newly created device context object. +\remark When calling this function the device context referred by the 'dev_ctx' argument must be in open session state. + +\remark The object allocated by this function can be acquired with xnd_xlt_devctx_acquire() and must be freed calling xnd_module_devctx_release() or xnd_xlt_devctx_release(); +\remark This feature is supported also on XLight version 2.50 and later. On XLight it is not necessary to open the session to call this function. +*/ +XND_LINK XND_DEVICE_CONTEXT XND_API xnd_module_devctx_create(XND_DEVICE_CONTEXT dev_ctx, unsigned int module_index, OPT OUT int* p_status); + +/** +\ingroup xnodus_modules +Release a device context context object pointed by a ::XND_DEVICE_CONTEXT handle created with xnd_module_devctx_create() (see \ref xnd_create_acquire_release), and release the module usage too. +\param[in] dev_ctx the ::XND_DEVICE_CONTEXT handle referencing to the object to release. +\return ::XND_ERROR_SUCCESS on success, an \ref xnodus_errors "error code" on failure, and ::XND_RELEASE_STILL_REFERENCED if there are still reference to the object. +*/ +XND_LINK int XND_API xnd_module_devctx_release(XND_DEVICE_CONTEXT dev_ctx); + +/** +\ingroup xnodus_modules +Return the module index of a device context. +\param[in] dev_ctx a ::XND_DEVICE_CONTEXT handle referring to the device context object. +\return return the module index of the device context. If no module is open on the device context or an error occurred the returned value is 0xFFFFFFFF. +*/ +XND_LINK unsigned int XND_API xnd_module_get_index(XND_DEVICE_CONTEXT dev_ctx); + +/** \defgroup xnodus_module_challenge_defs Module challenge constants +\ingroup xnodus_defines +Maximum lengths related to the used cryptographic key of the challenge argument passed to the function xnd_xlt_module_challenge() +@{ +*/ +#define XND_XLT_MODULE_CHALLENGE_RSA2048_MAX_LEN 254 ///< maximum length of the challenge argument of xnd_xlt_module_challenge() when RSA 2048 is used +#define XND_XLT_MODULE_CHALLENGE_RSA1024_MAX_LEN 126 ///< maximum length of the challenge argument of xnd_xlt_module_challenge() when RSA 1024 is used +#define XND_XLT_MODULE_CHALLENGE_RSA512_MAX_LEN 62 ///< maximum length of the challenge argument of xnd_xlt_module_challenge() when RSA 512 is used +#define XND_XLT_MODULE_CHALLENGE_AES_MAX_LEN 15 ///< maximum length of the challenge argument of xnd_xlt_module_challenge() when AES is used +// @} + +/** +\ingroup xnodus_modules +Run the module challenge function for testing if a given module is used or not (see \ref xnd_module_challenge). +\param[in] dev_ctx a ::XND_DEVICE_CONTEXT handle referring to a device context object with open session. +\param[in] key_type key type of the used key. This value takes values from \ref xnd_info_key_type. +\param[in] challenge points to a random buffer to be used for the module challenge and verification. +\param[in] challenge_len the length of the challange buffer. The length must be less than 16 if AES is used, If the key_type refers to a RSA key challenge_len must not exceed the length in bytes of the modulus minus two (see \ref xnodus_module_challenge_defs). +\param[in] module the module index to be queried (takes value from 0 to ::XND_MAX_NUM_MODULES -1 included). +\param[out] verify_buffer points to a buffer that will receive the value computed by xNodus or XLight. +\param[in] verify_buffer_size the size in bytes of verify_buffer. +\param[out] p_verify_buffer_len points to an unsigned integer that will receive the real length of verify_buffer. +\return ::XND_ERROR_SUCCESS on success, an \ref xnodus_errors "error code" on failure. +\remark This feature is supported also on XLight version 2.50 and later. On XLight it is not necessary to open the session to call this function. + +\remark The key_type entry identify the key to be used by the function. The addressed keys are the non volatile keys (see \ref xnd_non_volatile, xnd_non_volatile_key_set()). +On XLight the addressed key are set by the functions xnd_xlt_set_modules_key_cmd_wrap() and xnd_xlt_set_modules_key_apply(). +\see xnd_xlt_never_use_module_verify() +*/ +XND_LINK int XND_API xnd_xlt_module_challenge(XND_DEVICE_CONTEXT dev_ctx, unsigned int key_type, const unsigned char* challenge, unsigned int challenge_len, unsigned int module, unsigned char* verify_buffer, unsigned int verify_buffer_size, unsigned int* p_verify_buffer_len); + +/** +\ingroup xnodus_modules +Run the module verify function for testing if a given module is open or not (see \ref xnd_module_challenge). +\remark This function must be used only for testing purpose, don't use it in your release protected application. Write on your own the verification process. + +\param[in] dev_ctx a generic device context handle. +\param[in] key_type key type of used key. This value takes values from \ref xnd_info_key_type. +\param[in] key points to a buffer containing a key expressed in XLight or xNodus format (see \ref xnd_key_data). +\param[in] key_len the length of the key entry. +\param[in] challenge points to a buffer containing the same challange value used by xnd_xlt_module_challenge(). +\param[in] challenge_len the length of the challange buffer. +\param[in] module the module index as set in xnd_xlt_module_challenge(). +\param[in] verify_buffer points to the buffer returned by xnd_xlt_module_challenge(). +\param[in] verify_buffer_len the length of the verify_buffer entry. +\return ::XND_ERROR_SUCCESS on success, if the challenge-verification procedure fails it returns ::XND_ERROR_INVALID_ARGUMENT meaning the 'verify_buffer' doesn't represent a right buffer certificating the module as open. + +\see xnd_xlt_module_challenge() +*/ +XND_LINK int XND_API xnd_xlt_never_use_module_verify(XND_DEVICE_CONTEXT dev_ctx, unsigned int key_type, const unsigned char* key, unsigned int key_len, + const unsigned char* challenge, unsigned int challenge_len, unsigned int module, const unsigned char* verify_buffer, unsigned int verify_buffer_len); +//xnodus_modules + +/////////////////////////////////////////////////////////////////////////////////////////////////////////////////////// + +/** +\ingroup xnd_functions +Return information on the connected xNodus device +\param[in] dev_ctx a ::XND_DEVICE_CONTEXT handle referring to the device context object. +\param[out] p_xnd_info points to a ::XND_INFO structure that will receive the information from the xNodus device. +\return ::XND_ERROR_SUCCESS on success, an \ref xnodus_errors "error code" on failure. +*/ +XND_LINK int XND_API xnd_get_info(XND_DEVICE_CONTEXT dev_ctx, OUT P_XND_INFO p_xnd_info); + + +//admin_key_type is as in ::XND_INFO and ::XND_USER_INFO + +/** +\ingroup xnd_functions +Initialize a non initialized xNodus device. +\param[in] dev_ctx a ::XND_DEVICE_CONTEXT handle referring to a device context object with open session. +\param[in] label points to a 64 bytes buffer containing the label to be set on the xNodus device. +\param[in] service_key points to a 32 bytes buffer containing a key that will be used for cryptographic operation on xNodus. This value must be kept secret and never used inside the protected program. +\param[in] admin_key_type key type of the administrator key. This value takes values from \ref xnd_info_key_type. +\param[in] admin_key points to the buffer containing the adminstrator public key. It must be a formatted RSA public key (see \ref xnd_key_data) +\param[in] admin_key_len the length in bytes of the adminstrator key. +\param[in] xnodus_key_type key type of the xNodus public key. This value takes values from \ref xnd_info_key_type. +\param[in] xnodus_key points to the buffer containing the xNodus private RSA key. It must be a PQE formatted key or XLight style RSA private key (see \ref xnd_key_data) +\param[in] xnodus_key_len the length in bytes of the xNodus public key. +\return ::XND_ERROR_SUCCESS on success, an \ref xnodus_errors "error code" on failure. +\remark This function can be called only once, unless xnd_virginize() is called. + +\remark Note that 'admin_key' is a public RSA key, while 'xnodus_key' is a private RSA key. If both entries are set to 0, the device is initialized with the default values (that is the keys set during production by OxySec). + +\remark This function can be called only from an open session of the adminstrator user (see \ref xnd_users_types). +*/ +XND_LINK int XND_API xnd_init_device(XND_DEVICE_CONTEXT dev_ctx, const unsigned char* label, const unsigned char* service_key, + unsigned int admin_key_type, const unsigned char* admin_key, unsigned int admin_key_len, unsigned int xnodus_key_type, const unsigned char* xnodus_key, unsigned int xnodus_key_len); + +/** +\ingroup xnd_functions +Virginize an xNodus device. + +This function restores an xNodus device to its initial state. It deletes users if present, it deletes the xNodus label and the 'service_key' set by xnd_init_device(), +and restore the xNodus and adminstrator key to the default values from OxySec. The only unchanged values are the net settings and the licenses of the device. After calling this function it can be called xnd_init_device(). +\remark Never call this function on field. +\param[in] dev_ctx a ::XND_DEVICE_CONTEXT handle referring to a device context object with open session. +\return ::XND_ERROR_SUCCESS on success, an \ref xnodus_errors "error code" on failure. +\remark This function can be called only from an open session of the adminstrator user (see \ref xnd_users_types). +*/ +XND_LINK int XND_API xnd_virginize(XND_DEVICE_CONTEXT dev_ctx); + +/** +\ingroup xnd_functions +Set the network parameter of an xNodus device. +\param[in] dev_ctx a ::XND_DEVICE_CONTEXT handle referring to a device context object with open session. +\param[in] net_param points to a ::XND_NET_PARAM structure. +\return ::XND_ERROR_SUCCESS on success, an \ref xnodus_errors "error code" on failure. +*/ +XND_LINK int XND_API xnd_set_network_param(XND_DEVICE_CONTEXT dev_ctx, const XND_NET_PARAM* net_param); + +/** +\ingroup xnd_functions +Set the information that must visible using the xnd_get_info() function. +\param[in] dev_ctx a ::XND_DEVICE_CONTEXT handle referring to a device context object with open session. +\param[in] out_mask bitwise OR of the values from \ref xnd_significant_flag defining which data can be returned by xnd_get_info() when called outside a session. +\param[in] in_mask bitwise OR of the values from \ref xnd_significant_flag defining which data can be returned by xnd_get_info() when called inside a session by the 'Anonymous' and normal users (see \ref xnd_users_types). +\return ::XND_ERROR_SUCCESS on success, an \ref xnodus_errors "error code" on failure. +\remark This function can be called only from an open session of the adminstrator user (see \ref xnd_users_types). +*/ +XND_LINK int XND_API xnd_set_visible_info(XND_DEVICE_CONTEXT dev_ctx, unsigned int out_mask, unsigned int in_mask); + + +/** +\ingroup xnd_list_username +Create a ::XND_USER_FIND object to start a normal user (see \ref xnd_users_types) enumeration on an xNodus device. +\param[in] dev_ctx a ::XND_DEVICE_CONTEXT handle referring to a device context object with open session. +\return an handle of a ::XND_USER_FIND object. +\remark The value returned by this function must be always freed calling xnd_get_user_list_finalize(). + +\see xnd_get_user_list_next(), xnd_get_user_list_finalize(). +*/ +XND_LINK XND_USER_FIND XND_API xnd_get_user_list_start(XND_DEVICE_CONTEXT dev_ctx); + +//\cond NOT_COMMENTED +//XND_LINK int XND_API xnd_get_user_list_start(XND_DEVICE_CONTEXT dev_ctx, void* dev_ctx); +XND_LINK int XND_API xnd_reserved1(XND_DEVICE_CONTEXT dev_ctx, void* xnd_user_find); +//\endcond + +/** +\ingroup xnd_list_username +Return the next username of the list of normal users (see \ref xnd_users_types) present on an xNodus device. +\param[in] xnd_find an handle of type ::XND_USER_FIND returned by xnd_get_user_list_start(). +\param[out] user_name points to a structure of type ::XND_USER_NAME that will contain the next username found. +\return ::XND_ERROR_SUCCESS on success, return XND_ERROR_DEV_USER_NO_MORE_USER_AVAILABLE when no more users are present, an \ref xnodus_errors "error code" on failure. +\remark The 'Anonymous' and 'Administrator' users (see \ref xnd_users_types) are not listed. + +\see xnd_get_user_list_start(), xnd_get_user_list_finalize(). +*/ +XND_LINK int XND_API xnd_get_user_list_next(XND_USER_FIND xnd_find, OUT P_XND_USER_NAME user_name); +//\cond NOT_COMMENTED +XND_LINK int XND_API xnd_reserved2(void* xnd_find, XND_DEVICE_CONTEXT dev_ctx, OUT P_XND_USER_NAME user_name); +//\endcond + +/** +\ingroup xnd_list_username +Finalize an xNodus username search. +\param[in] xnd_find an handle of type ::XND_USER_FIND returned by xnd_get_user_list_start(). +\return ::XND_ERROR_SUCCESS on success, an \ref xnodus_errors "error code" on failure. +\remark This function can be called also before the search has been completed. + +\remark This function can be called only from an administrator session. +\see xnd_get_user_list_start(), xnd_get_user_list_next(). +*/ +XND_LINK int XND_API xnd_get_user_list_finalize(XND_USER_FIND xnd_find); + +/** +\ingroup xnd_list_username_idx +Create a ::XND_USER_FIND_IDX object to start a normal user (see \ref xnd_users_types) enumeration on an xNodus device returning also the internal index value of each user. +\param[in] dev_ctx a ::XND_DEVICE_CONTEXT handle referring to a device context object with open session. +\return an handle of a ::XND_USER_FIND_IDX object. +\remark The value returned by this function must be always freed calling xnd_get_user_list_idx_finalize(). + +\see xnd_get_user_list_idx_next(), xnd_get_user_list_idx_finalize(). +*/ +XND_LINK XND_USER_FIND_IDX XND_API xnd_get_user_list_idx_start(XND_DEVICE_CONTEXT dev_ctx); +//\cond NOT_COMMENTED +XND_LINK int XND_API xnd_reserved3(XND_DEVICE_CONTEXT dev_ctx, void* xnd_user_find); +//\endcond + +/** +\ingroup xnd_list_username_idx +Return the next username and its index from the list of normal users (see \ref xnd_users_types) present on an xNodus device. +\param[in] xnd_find an handle of type ::XND_USER_FIND_IDX returned by xnd_get_user_list_idx_start(). +\param[out] user_name points to a structure of type ::XND_USER_NAME that will contain the next username found. +\param[out] p_user_index points to an unsigned integer that will receive the internal identification index of the user. This entry may be set to 0. +\return ::XND_ERROR_SUCCESS on success, return XND_ERROR_DEV_USER_NO_MORE_USER_AVAILABLE when no more users are present, an \ref xnodus_errors "error code" on failure. +\remark The 'Anonymous' and 'Administrator' users (see \ref xnd_users_types) are not listed. + +\see xnd_get_user_list_idx_start(), xnd_get_user_list_idx_finalize(). +*/ +XND_LINK int XND_API xnd_get_user_list_idx_next(XND_USER_FIND_IDX xnd_find, OPT OUT P_XND_USER_NAME user_name, OPT OUT unsigned int* p_user_index); + +//\cond NOT_COMMENTED +XND_LINK int XND_API xnd_reserved4(void* xnd_find, XND_DEVICE_CONTEXT dev_ctx, OPT OUT P_XND_USER_NAME user_name, OPT OUT unsigned int* p_user_index); +//\endcond + +/** +\ingroup xnd_list_username_idx +Finalize an xNodus username and index search. +\param[in] xnd_find an handle of type ::XND_USER_FIND_IDX returned by xnd_get_user_list_idx_start(). +\return ::XND_ERROR_SUCCESS on success, an \ref xnodus_errors "error code" on failure. +\remark This function can be called also before the search has been completed. + +\see xnd_get_user_list_idx_start(), xnd_get_user_list_idx_next(). +*/ +XND_LINK int XND_API xnd_get_user_list_idx_finalize(XND_USER_FIND_IDX xnd_find); + +/** +\ingroup xnd_user_man +Return user information of an 'Anoymous' or normal user (see \ref xnd_users_types). +\param[in] dev_ctx a ::XND_DEVICE_CONTEXT handle referring to a device context object with open session. +\param[in] user_name points to a structure of type ::XND_USER_NAME containing the name of the user to get information. +\param[out] p_user_info points to structure of type ::XND_USER_INFO containing the user information. +\return ::XND_ERROR_SUCCESS on success, an \ref xnodus_errors "error code" on failure. +\remark This function can be called from an adminstrator session to get information of every user, an 'Anoymous' or normal user can get only its own information. +*/ +XND_LINK int XND_API xnd_get_user_info(XND_DEVICE_CONTEXT dev_ctx, const XND_USER_NAME* user_name, OUT P_XND_USER_INFO p_user_info); + +/** +\ingroup xnd_user_man +Return information of the current 'Anoymous' or normal user (see \ref xnd_users_types). +\param[in] dev_ctx a ::XND_DEVICE_CONTEXT handle referring to a device context object with open session. +\param[out] p_user_info points to structure of type ::XND_USER_INFO containing the user information. +\return ::XND_ERROR_SUCCESS on success, an \ref xnodus_errors "error code" on failure. +\see xnd_get_user_info(). +*/ +XND_LINK int XND_API xnd_get_current_user_info(XND_DEVICE_CONTEXT dev_ctx, OUT P_XND_USER_INFO p_user_info); + +/** +\ingroup xnd_user_man +Create a normal user (see \ref xnd_users_types). +\param[in] dev_ctx a ::XND_DEVICE_CONTEXT handle referring to a device context object with open session. +\param[in] p_user_info points to a structure of type ::XND_USER_INFO containing the configuration settings for the new user. +\return ::XND_ERROR_SUCCESS on success, an \ref xnodus_errors "error code" on failure. +\remark It is recommended to set the permission_mask entry of the ::XND_USER_INFO structure with the ::XND_PMASK_USER_DEFAULT value. + +\remark This function can be called only from an administrator session. +*/ +XND_LINK int XND_API xnd_create_user(XND_DEVICE_CONTEXT dev_ctx, const XND_USER_INFO* p_user_info); + +/** +\ingroup xnd_user_man +Update an 'Anonymous' or normal user (see \ref xnd_users_types). +\param[in] dev_ctx a ::XND_DEVICE_CONTEXT handle referring to a device context object with open session. +\param[in] p_user_info points to a structure of type ::XND_USER_INFO containing the changed configuration settings for the user. +\return ::XND_ERROR_SUCCESS on success, an \ref xnodus_errors "error code" on failure. +\remark It is recommended to set the permission_mask entry of the ::XND_USER_INFO structure with the ::XND_PMASK_USER_DEFAULT value for the normal user, and ::XND_PMASK_USER_ANONYMOUS_DEFAULT for the 'Anonymous' user. + +\remark This function can be called only from an administrator session. +*/ +XND_LINK int XND_API xnd_update_user(XND_DEVICE_CONTEXT dev_ctx, const XND_USER_INFO* p_user_info); + +/** +\ingroup xnd_user_man +Delete a normal user (see \ref xnd_users_types). +\param[in] dev_ctx a ::XND_DEVICE_CONTEXT handle referring to a device context object with open session. +\param[in] user_name points to a structure of type ::XND_USER_NAME containing the name of the normal user to be deleted. +\return ::XND_ERROR_SUCCESS on success, an \ref xnodus_errors "error code" on failure. +\remark This function can be called only from an administrator session. +*/ +XND_LINK int XND_API xnd_delete_user(XND_DEVICE_CONTEXT dev_ctx, const XND_USER_NAME* user_name); + +/** +\ingroup xnd_user_man +Change the cryptographic key of a normal user (see \ref xnd_users_types). +\param[in] dev_ctx a ::XND_DEVICE_CONTEXT handle referring to a device context object with open session. +\param[in] user_name points to a structure of type ::XND_USER_NAME containing the name of the normal user for which the password must be changed. +\param[in] key_type key type of the new key. This value takes values from \ref xnd_info_key_type. +\param[in] key points to the buffer containing the new key. It must be a PQE formatted key or XLight style RSA key (see \ref xnd_key_data) +\param[in] key_len the length in bytes of the new key. +\return ::XND_ERROR_SUCCESS on success, an \ref xnodus_errors "error code" on failure. +\remark The administrator user can change the key of every normal user but not its own key (the only way to change the administrator password is to reprogram the xNodus device). Each normal user can change only its own password. +*/ +XND_LINK int XND_API xnd_change_user_key(XND_DEVICE_CONTEXT dev_ctx, const XND_USER_NAME* user_name, unsigned int key_type, const unsigned char* key, unsigned int key_len); + +/** +\ingroup xnd_functions +Start the Secure Boot Loader (SBL) of the device (see \ref xnd_sbl). +\param[in] dev_ctx a ::XND_DEVICE_CONTEXT handle referring to a device context object with open session. +\return ::XND_ERROR_SUCCESS on success, an \ref xnodus_errors "error code" on failure. +\remark This function can be called from an administrator session. It can be called also from an 'Anonymous' or normal user if the permission mask allows this task (used ::XND_PMASK_SS_START_SBL). +*/ +XND_LINK int XND_API xnd_start_sbl(XND_DEVICE_CONTEXT dev_ctx); + +/** +\ingroup xnd_functions +Immediately close all open sessions except that of the function caller. Usually only the administrator user is allowed to call this function. +\param[in] dev_ctx a ::XND_DEVICE_CONTEXT handle referring to a device context object with open session. +\return ::XND_ERROR_SUCCESS if found, an \ref xnodus_errors "error code" on failure. +\remark This function can be called from an administrator session. +*/ +XND_LINK int XND_API xnd_close_all_sessions(XND_DEVICE_CONTEXT dev_ctx); + +/** +\ingroup xnd_functions +Virginize a virtual XLight device (see \ref xnd_virtual_xlight). + +This function restore a virtual XLight of an xNodus device to its non programmed state. + +It is analogous to the xnd_xlt_virg_demo() applied on real XLight device with the relevant difference that in this case it can be applied to every non demo device. +\param[in] dev_ctx a ::XND_DEVICE_CONTEXT handle referring to a device context object with open session. +\param[in] xlight_index index of the virtual XLight to be virginized. +\return ::XND_ERROR_SUCCESS on success, an \ref xnodus_errors "error code" on failure. +\remark This function can be called by the Administrator user. 'Anonymous' and normal users also can call this function as well but the default and suggested permission settings prevent them to run this function. +Whenever the permission is given also to these users they can just virginize only their own virtual XLight device. +*/ +XND_LINK int XND_API xnd_virginize_xlight(XND_DEVICE_CONTEXT dev_ctx, unsigned int xlight_index); + +/** +\ingroup xnd_non_volatile_g +Set a non-volatile cryptographic key on an xNodus device (see \ref xnd_non_volatile). +\param[in] dev_ctx a ::XND_DEVICE_CONTEXT handle referring to a device context object with open session. +\param[in] key_type key type of the passed key. This value takes values from \ref xnd_info_key_type. +\param[in] key points to the buffer containing the non volatile key. It must be a PQE formatted key or XLight style RSA key (see \ref xnd_key_data) +\param[in] key_len the length in bytes of the key. +\return ::XND_ERROR_SUCCESS on success, an \ref xnodus_errors "error code" on failure. +\remark This function can be called by the Administrator user. 'Anonymous' and normal users also can call this function as well but the default and suggested permission settings prevent them to run this function. + +\remark It is possible to perform the volatile key setting also using a remote command using xnd_remote_cmd_non_volatile_key_set() and +\see xnd_non_volatile_encrypt(), xnd_non_volatile_decrypt(). +*/ +XND_LINK int XND_API xnd_non_volatile_key_set(XND_DEVICE_CONTEXT dev_ctx, unsigned int key_type, const unsigned char* key, unsigned int key_len); + +/** +\ingroup xnd_non_volatile_g +Perform a RSA encryption using a non-volatile key (see \ref xnd_non_volatile). +\param[in] dev_ctx a ::XND_DEVICE_CONTEXT handle referring to a device context object with open session. +\param[in] key_type type of the key to be used. The type identify also which key must be kept. This value takes values from \ref xnd_info_key_type. +\param[in] plaintext points to a buffer containing the data to encrypt. +\param[in] plaintext_len the length of the plaintext. It must be equal to the byte length of the key (for instance 256 bytes for a 2048 bit key). +\param[out] ciphertext points to a buffer that will receive the encrypted data. The returned buffer has the same length of the plaintext. +\return ::XND_ERROR_SUCCESS on success, an \ref xnodus_errors "error code" on failure. +\see xnd_non_volatile_key_set(), xnd_non_volatile_decrypt(). +*/ +XND_LINK int XND_API xnd_non_volatile_encrypt(XND_DEVICE_CONTEXT dev_ctx, unsigned int key_type, const unsigned char* plaintext, unsigned int plaintext_len, unsigned char* ciphertext); + +/** +\ingroup xnd_non_volatile_g +Perform a RSA decryption using a non-volatile key (see \ref xnd_non_volatile). +\param[in] dev_ctx a ::XND_DEVICE_CONTEXT handle referring to a device context object with open session. +\param[in] key_type type of the key to be used. The type identify also which key must be kept. This value takes values from \ref xnd_info_key_type. +\param[in] ciphertext points to a buffer containing the data to decrypt. +\param[in] ciphertext_len the length of the ciphertext. It must be equal to the byte length of the key (for instance 256 bytes for a 2048 bit key). +\param[out] plaintext points to a buffer that will receive the decrypted data. The returned buffer has the same length of the ciphertext. +\return ::XND_ERROR_SUCCESS on success, an \ref xnodus_errors "error code" on failure. +\see xnd_non_volatile_key_set(), xnd_non_volatile_encrypt(). +*/ +XND_LINK int XND_API xnd_non_volatile_decrypt(XND_DEVICE_CONTEXT dev_ctx, unsigned int key_type, const unsigned char* ciphertext, unsigned int ciphertext_len, unsigned char* plaintext); + +/** +\ingroup xnd_functions +Change the permissions of a user (see \ref xnd_users_types). +\param[in] dev_ctx a ::XND_DEVICE_CONTEXT handle referring to a device context object with open session. +\param[in] user_name points to a structure of type ::XND_USER_NAME with the name of the user to which the permission mask must be changed +\param[in] mask the new permission mask composed with bitwise OR of a collection of values from \ref xnd_permision_mask. +\return ::XND_ERROR_SUCCESS on success, an \ref xnodus_errors "error code" on failure. +\remark This function can be called only by the Administrator user. +*/ +XND_LINK int XND_API xnd_set_permission_mask(XND_DEVICE_CONTEXT dev_ctx, const XND_USER_NAME* user_name, XLT_ULONG_LONG mask); + +/** +\ingroup xnd_volatile_g +Wrap a non-volatile key (see \ref xnd_volatile). +\param[in] dev_ctx ::XND_DEVICE_CONTEXT handle referring to a real or fake device. +\param[in] key points to the AES key that must be used onto xNodus. +\param[in] key_len length in byte of the AES key. +\param[in] service_key the 32 byte key set by xnd_init_device(). +\param[out] wrapped_key_32 points to a 32 byte buffer that will receive the result of the AES key wrapping. +\return ::XND_ERROR_SUCCESS on success, an \ref xnodus_errors "error code" on failure. +\remark Never use this function inside the protected program. +*/ +XND_LINK int XND_API xnd_volatile_key_wrap(XND_DEVICE_CONTEXT dev_ctx, const unsigned char* key, unsigned int key_len, const unsigned char* service_key, unsigned char* wrapped_key_32); + +/** +\ingroup xnd_volatile_g +Set a volatile key inside the xNodus device (see \ref xnd_volatile). +\param[in] dev_ctx a ::XND_DEVICE_CONTEXT handle referring to a device context object with open session. +\param[in] wrapped_key points to a 32 byte buffer containing the AES key wrapped with the xnd_volatile_key_wrap() function. +\return ::XND_ERROR_SUCCESS on success, an \ref xnodus_errors "error code" on failure. +*/ +XND_LINK int XND_API xnd_volatile_key_set(XND_DEVICE_CONTEXT dev_ctx, const unsigned char* wrapped_key); + +/** +\defgroup xnd_encryption_mode Encryption mode of operation of the volatile encryption functions. +\ingroup xnodus_defines +The supported encryption modes are: +

        +
      1. ECB (Electronic Codebook mode) +
      2. CBC (Cipher Block Chaining) +
      3. IGE (Infinite Garble Extension) +
      4. GCM (Galois Counter Mode) +
      + +@{ +*/ +#define XND_ENCRYPTION_MODE_ECB 0 ///< ECB encryption mode +#define XND_ENCRYPTION_MODE_CBC 1 ///< CBC encryption mode +#define XND_ENCRYPTION_MODE_IGE 2 ///< IGE encryption mode +#define XND_ENCRYPTION_MODE_GCM 3 ///< GCM encryption mode + +//@} //xnd_encryption_mode + +/** +\ingroup xnd_volatile_g +Perform a volatile encryption (see \ref xnd_volatile). +\param[in] dev_ctx a ::XND_DEVICE_CONTEXT handle referring to a device context object with open session. +\param[in] key_byte_len the length in byte of the AES key (32, 24 or 16). +\param[in] mode_of_operation mode of operation of the encryption selected using the values from /ref xnd_encryption_mode. +\param[in] plaintext points to the buffer containing the data to encrypt. +\param[in] plaintext_len the length of the plaintext. This value must be a multiple of 16. +\param[in] ini_vect points to buffer containing the initialization vector for the CBC or GCM mode. In case of CBC 16 bytes will be considered, while for GCM 12 bytes are taken. This entry may be set to 0 for ECB, IGE and also for CBC mode. +\param[in] gcm_aad_len the length of the AAD (additional authenticated data) part of the plaintext when using GCM. The AAD part is the heading part of the plaintext buffer and its length must be not grater than the plaintext length. 'gcm_aad_len' must be set to '0' using the other encryption modes and can be set to 0 with GCM. This value must be a multiple of 16. +\param[out] ciphertext points to a buffer that will receive the result of the encryption operation. +\param[in] ciphertext_size the length in bytes of the buffer pointed by the 'ciphertext' argument. +\param[out] p_ciphertext_len points to a buffer that will receive the length of the returned ciphertext. +\return ::XND_ERROR_SUCCESS on success, an \ref xnodus_errors "error code" on failure. +The original GCM doesn't have the restrictions present here (including the multiple of 16 requests) to exploit the hardware encryption supplied by the device. +\note Every user can run this function. +*/ +XND_LINK int XND_API xnd_volatile_encrypt(XND_DEVICE_CONTEXT dev_ctx, unsigned int key_byte_len, unsigned int mode_of_operation, const unsigned char* plaintext, unsigned int plaintext_len, OPT const unsigned char* ini_vect, OPT unsigned int gcm_aad_len, unsigned char* ciphertext, unsigned int ciphertext_size, OPT OUT unsigned int* p_ciphertext_len); + +/** +\ingroup xnd_volatile_g +Perform a volatile decryption (see \ref xnd_volatile). +\param[in] dev_ctx a ::XND_DEVICE_CONTEXT handle referring to a device context object with open session. +\param[in] key_byte_len the length in byte of the AES key (32, 24 or 16). +\param[in] mode_of_operation mode of operation of the encryption selected using the values from /ref xnd_encryption_mode. +\param[in] ciphertext points to a buffer containing the data to be decrypted. +\param[in] ciphertext_len the length of the ciphertext. This value must be a multiple of 16. +\param[in] ini_vect points to buffer containing the initialization vector for the CBC or GCM mode. In case of CBC 16 bytes will be considered, while for GCM 12 bytes are taken. This entry may be set to 0 for ECB, IGE and also for CBC mode. +\param[in] gcm_aad_len the length of the AAD (additional authenticated data) part of the plaintext when using GCM. The AAD part is the heading part of the plaintext buffer and its length must be not grater than the plaintext length. 'gcm_aad_len' must be set to '0' using the other encryption modes and can be set to 0 with GCM. This value must be a multiple of 16. +\param[out] plaintext points to a buffer that will receive the result of the decryption operation. +\param[in] plaintext_size the length in bytes of the buffer pointed by the 'plaintext' argument. +\param[out] p_plaintext_len points to a buffer that will receive the length of the returned plaintext. +\return ::XND_ERROR_SUCCESS on success, an \ref xnodus_errors "error code" on failure. +The original GCM doesn't have the restrictions present here (including the multiple of 16 requests) to exploit the hardware encryption supplied by the device. +\note Every user can run this function. +*/ +XND_LINK int XND_API xnd_volatile_decrypt(XND_DEVICE_CONTEXT dev_ctx, unsigned int key_byte_len, unsigned int mode_of_operation, const unsigned char* ciphertext, unsigned int ciphertext_len, OPT const unsigned char* ini_vect, OPT unsigned int gcm_aad_len, unsigned char* plaintext, unsigned int plaintext_size, OPT unsigned int* p_plaintext_len); + +/** +\ingroup xnd_functions +Test function for manage the 'session check' procedure system (see \ref xnd_session_check) +\param[in] key a ::XND_KEY_DATA handle to a cryptographic key corresponding to the used non non volatile key present on xNodus. +\param[in] counter_value the progressive counter of the session check procedure. +\param[in] random_data points to the random data needed for the procedure +\param[in] random_data_len the length of the random data. This value must be 12 for AES encryption or the length of the public module expressed in byte minus '4' when using RSA. +\param[out] enc_msg points to a buffer that will receive the computed value to be send to the xNodus device. +\param[in] enc_msg_size the size in byte of the buffer pointed by the 'enc_msg' entry. +\param[out] p_enc_msg_len points to an unsigned integer that will receive the real length of the computed value written in 'enc_msg'. If set to '0' the length is not retrieved. +\return ::XND_ERROR_SUCCESS on success, an \ref xnodus_errors "error code" on failure. +\note This function is present for testing purpose, never use it in the application protected with xNodus. +\see xnd_start_session_check(), xnd_continue_session_check(). +*/ +XND_LINK int XND_API xnd_never_use_session_check_prepare(XND_KEY_DATA key, unsigned int counter_value, const unsigned char* random_data, unsigned int random_data_len, unsigned char* enc_msg, unsigned int enc_msg_size, unsigned int* p_enc_msg_len); + +/** +\ingroup xnd_functions +Start a 'session check' procedure (see \ref xnd_session_check). +\param[in] dev_ctx a ::XND_DEVICE_CONTEXT handle referring to a device context object with open session. +\param[in] key_type key type of the desired non volatile key. This value takes values from \ref xnd_info_key_type. +\param[in] enc_msg points to a buffer containing the encrypted data that starts the session check procedure (computed by xnd_never_use_session_check_prepare() or, better, equivalent functions). +\param[in] enc_msg_len the length of the 'enc_msg' entry. +\param[out] dec_msg points to a buffer that will receive the data produced by by xNodus (a decryption of the incoming data). +\param[in] dec_msg_size the size in byte of the buffer pointed by the 'dec_msg' entry. +\param[out] p_dec_msg_len points to an unsigned integer that will receive the real length of the computed value written in 'dec_msg'. If set to '0' the length is not retrieved. +\return ::XND_ERROR_SUCCESS on success, an \ref xnodus_errors "error code" on failure. +\see xnd_continue_session_check(), xnd_never_use_session_check_prepare(). +*/ +XND_LINK int XND_API xnd_start_session_check(XND_DEVICE_CONTEXT dev_ctx, unsigned int key_type, const unsigned char* enc_msg, unsigned int enc_msg_len, unsigned char* dec_msg, unsigned int dec_msg_size, unsigned int* p_dec_msg_len); + +/** +\ingroup xnd_functions +Continue a 'session check' procedure (see \ref xnd_session_check). +\param[in] dev_ctx a ::XND_DEVICE_CONTEXT handle referring to a device context object with open session. +\param[in] key_type key type of the desired non volatile key. This value takes values from \ref xnd_info_key_type. +\param[in] enc_msg points to a buffer containing the encrypted data that starts the session check procedure (computed by xnd_never_use_session_check_prepare() or, better, equivalent functions). +\param[in] enc_msg_len the length of the 'enc_msg' entry. +\param[out] dec_msg points to a buffer that will receive the data produced by by xNodus (a decryption of the incoming data). +\param[in] dec_msg_size the size in byte of the buffer pointed by the 'dec_msg' entry. +\param[out] p_dec_msg_len points to an unsigned integer that will receive the real length of the computed value written in 'dec_msg'. If set to '0' the length is not retrieved. +\return ::XND_ERROR_SUCCESS on success, an \ref xnodus_errors "error code" on failure. +\see xnd_start_session_check(), xnd_never_use_session_check_prepare(). +*/ +XND_LINK int XND_API xnd_continue_session_check(XND_DEVICE_CONTEXT dev_ctx, unsigned int key_type, const unsigned char* enc_msg, unsigned int enc_msg_len, unsigned char* dec_msg, unsigned int dec_msg_size, unsigned int* p_dec_msg_len); + +/** +\ingroup xnd_functions +Return a true (hardware) random number. +\param[in] dev_ctx a ::XND_DEVICE_CONTEXT handle referring to a device context object with open session. +\param[out] random points to a buffer that will receive the random buffer. +\param[in] len the length in bytes of the desired random buffer. +\return ::XND_ERROR_SUCCESS on success, an \ref xnodus_errors "error code" on failure. +*/ +XND_LINK int XND_API xnd_get_true_random(XND_DEVICE_CONTEXT dev_ctx, OUT unsigned char* random, unsigned int len); + +/** +Start SBL (Secure Boot Loader) command structure for remote command + +This is the structure of the remote start boot loader command. +In order to perform a remote reboot it is necessary set the serial number (just the final four bytes of the sixteen overall) +and set a counter greater than the current one. Both values are returned by xnd_get_info(). + +It is suggested to use the unix time for destination_counter: this allow to avoid to read its value and grant to use a value +greater than the previous one + +SBL (Secure Boot Loader) is the xNodus configuration that is used to update the firmware: only a OxySec signed firmware can be uploaded. +When a device is in SBL configuration it can't do anything but update the firmware to a newer version. +*/ +typedef struct _REMOTE_SBL_CMD { + unsigned char destination_serial_part[4]; ///< Final four bytes of the device serial number of the destination xNodus device (XND_INFO.sn). + unsigned int destination_counter; ///< Counter of the operation (must be grater than XND_INFO.remote_counter). +}REMOTE_SBL_CMD; +typedef REMOTE_SBL_CMD *P_REMOTE_SBL_CMD; ///< pointer to ::REMOTE_SBL_CMD type + + +/** +Start SBL (Secure Boot Loader) response structure for remote command + +This is the structure of the remote start boot loader command answer. It contains the argument of the command and the status of the operation +*/ +typedef struct _REMOTE_SBL_RESP { + REMOTE_SBL_CMD issued_cmd; ///< arguments of the remote start boot loader command sent to the device + int status; ///< the status of the operation returned by the device +}REMOTE_SBL_RESP; +typedef REMOTE_SBL_RESP *P_REMOTE_SBL_RESP; ///< pointer to ::REMOTE_SBL_RESP type + +/** +\ingroup xnodus_remote_cmd +Write a buffer for the remote execution of the start of the Secure Boot Loader on a given device. +\param[in] dev_ctx an administrator device context object handle. +\param[in] remote_sbl_cmd points to a structure ::REMOTE_SBL_CMD with the arguments of the command. +\param[out] enc_cmd points to a buffer that will receive the command buffer to be remotely applied to the device using xnd_apply_remote_command() +\param[in] enc_cmd_size the size of the buffer pointed by 'enc_cmd'. +\param[out] p_enc_cmd_len points to an unsigned integer that will receive the length of the command pointed by 'enc_cmd'. +\return ::XND_ERROR_SUCCESS if found, an \ref xnodus_errors "error code" on failure. +\remark To apply the command to the xNodus device it is necessary run xnd_apply_remote_command() in an application that can communicate directly to the target xNodus device. As input it needs the generated encrypted command +(i.e. the result pointed by enc_cmd). If it is necessary to know the result of the operation of xnd_apply_remote_command(), the function xnd_remote_resp_start_sbl() can analyze the response to the command. +\see xnd_apply_remote_command(), xnd_remote_resp_start_sbl(). +*/ +XND_LINK int XND_API xnd_remote_cmd_start_sbl(XND_DEVICE_CONTEXT dev_ctx, const REMOTE_SBL_CMD* remote_sbl_cmd, OUT unsigned char* enc_cmd, unsigned int enc_cmd_size, OUT unsigned int* p_enc_cmd_len); + +/** +\ingroup xnodus_remote_cmd +Retrieve the status of a remote start 'Secure Boot Loader' call +\param[in] dev_ctx an administrator device context object handle. +\param[in] enc_resp points to a buffer containing the response of xNodus returned by the function xnd_apply_remote_command(). +\param[in] enc_resp_len the length of the buffer pointed by 'enc_resp'. +\param[out] p_resp points to a struct of type ::REMOTE_SBL_RESP that will be filled with the status and data of the remote operation. +\return ::XND_ERROR_SUCCESS if found, an \ref xnodus_errors "error code" on failure. +\see xnd_remote_cmd_start_sbl(). +*/ +XND_LINK int XND_API xnd_remote_resp_start_sbl(XND_DEVICE_CONTEXT dev_ctx, const unsigned char* enc_resp, unsigned int enc_resp_len, OUT P_REMOTE_SBL_RESP p_resp); + +/** +Non volatile key set command structure for remote command + +This is the structure of the remote 'non volatile key set' command. +In order to perform a remote 'non volatile key set' it is necessary (in addition to the key values) set the serial number (just the final four bytes of the sixteen overall) +and set a counter greater than the current one. Both values are returned by xnd_get_info(). + +It is suggested to use the unix time for destination_counter: this allow to avoid to read its value and grant to use a value +greater than the previous one +*/ +typedef struct _REMOTE_NON_VOLATILE_KEY_SET_CMD { + unsigned int key_type; ///< type of cryptographic key to be set (values from \ref xnd_info_key_type). + unsigned int key_len; ///< length of cryptographic key + unsigned char key[XND_RSA_4096_PRIV_KEY_SIZE];///< cryptographic key to be set expressed in XLight or xNodus format (see \ref xnd_key_data). + unsigned char destination_serial_part[4];///< final four bytes of the xNodus device serial number (XND_INFO.sn). + unsigned int destination_counter; ///< counter of the operation (must be grater than XND_INFO.remote_counter). +}REMOTE_NON_VOLATILE_KEY_SET_CMD; +typedef REMOTE_NON_VOLATILE_KEY_SET_CMD *P_REMOTE_NON_VOLATILE_KEY_SET_CMD; ///< pointer to ::REMOTE_NON_VOLATILE_KEY_SET_CMD type + +/** +Non volatile key set response structure for remote command + +This is the structure of the remote 'non volatile key set' command answer. It contains the argument of the command and the status of the operation +*/ +typedef struct _REMOTE_NON_VOLATILE_KEY_SET_RESP { + REMOTE_NON_VOLATILE_KEY_SET_CMD issued_cmd; ///< arguments of the remote non volatile set key command sent to the device + int status; ///< the status of the operation returned by the device +}REMOTE_NON_VOLATILE_KEY_SET_RESP; +typedef REMOTE_NON_VOLATILE_KEY_SET_RESP *P_REMOTE_NON_VOLATILE_KEY_SET_RESP; ///< pointer to ::REMOTE_NON_VOLATILE_KEY_SET_RESP type + +/** +\ingroup xnodus_remote_cmd +Set a non volatile key remotely. + +Construct a remote command buffer to perform the same task of the xnd_non_volatile_key_set() function. +\param[in] dev_ctx an administrator device context object handle. +\param[in] cmd points to a structure ::REMOTE_NON_VOLATILE_KEY_SET_CMD with the arguments of the command. +\param[out] enc_cmd points to a buffer that will receive the command buffer to be remotely applied to the device using xnd_apply_remote_command(). +\param[in] enc_cmd_size the size of the buffer pointed by 'enc_cmd'. +\param[out] p_enc_cmd_len points to an unsigned integer that will receive the length of the command pointed by 'enc_cmd'. +\return ::XND_ERROR_SUCCESS if found, an \ref xnodus_errors "error code" on failure. +\remark To apply the command to the xNodus device it is necessary run xnd_apply_remote_command() in an application that can communicate directly to the target xNodus device. As input it needs the generated encrypted command +(i.e. the result pointed by enc_cmd). If it is necessary to know the result of the operation of xnd_apply_remote_command(), the function xnd_remote_resp_non_volatile_key_set() can analyze the response to the command. +\see xnd_remote_resp_non_volatile_key_set(), xnd_apply_remote_command(). +*/ +XND_LINK int XND_API xnd_remote_cmd_non_volatile_key_set(XND_DEVICE_CONTEXT dev_ctx, const REMOTE_NON_VOLATILE_KEY_SET_CMD* cmd, OUT unsigned char* enc_cmd, unsigned int enc_cmd_size, OUT unsigned int* p_enc_cmd_len); + +/** +\ingroup xnodus_remote_cmd + +Retrieve the status of a remote 'non volatile key set' command. +\param[in] dev_ctx an administrator device context object handle. +\param[in] enc_resp points to a buffer containing the response of xNodus returned by the function xnd_apply_remote_command(). +\param[in] enc_resp_len the length of the buffer pointed by 'enc_resp'. +\param[out] p_resp points to a struct of type ::REMOTE_NON_VOLATILE_KEY_SET_RESP that will be filled with the status and data of the remote operation. +\return ::XND_ERROR_SUCCESS if found, an \ref xnodus_errors "error code" on failure. + +\see xnd_remote_cmd_non_volatile_key_set(), xnd_apply_remote_command(). +*/ +XND_LINK int XND_API xnd_remote_resp_non_volatile_key_set(XND_DEVICE_CONTEXT dev_ctx, const unsigned char* enc_resp, unsigned int enc_resp_len, OUT P_REMOTE_NON_VOLATILE_KEY_SET_RESP p_resp); + + +/** +User create and update command structure for remote command + +This is the structure of the remote 'create user' (see xnd_create_user()) and 'update user' command (see xnd_update_user()). +In order to perform a remote 'create user' or 'update user' it is necessary set the serial number (just the final four bytes of the sixteen overall) +and set a counter greater than the current one. Both values are returned by xnd_get_info(). + +It is suggested to use the unix time for destination_counter: this allow to avoid to read its value and grant to use a value +greater than the previous one +*/ +typedef struct _REMOTE_UPDATE_USER_CMD { + unsigned int is_update; ///< if set to 0 this is a remote 'create user' command, otherwise it is an 'update user' command + unsigned int _unused; ///< unused + XND_USER_INFO user_info; ///< value to be set remotely. In case of update the entry set_values_mask can be used to change a subset of values. + unsigned char destination_serial_part[4];///< final four bytes of the xNodus device serial number(XND_INFO.sn). + unsigned int destination_counter; ///< counter of the operation (must be grater than XND_INFO.remote_counter). +}REMOTE_UPDATE_USER_CMD; +typedef REMOTE_UPDATE_USER_CMD *P_REMOTE_UPDATE_USER_CMD; ///< pointer to ::REMOTE_UPDATE_USER_CMD type + +/** +User create and update response structure for remote command + +This is the structure of the remote user create and update command answer. It contains the argument of the command and the status of the operation +*/ +typedef struct _REMOTE_UPDATE_USER_RESP { + REMOTE_UPDATE_USER_CMD issued_cmd; ///< arguments of the 'create and update user' command sent to the device + int status; ///< the status of the operation returned by the device + unsigned int _unused; ///< unused +}REMOTE_UPDATE_USER_RESP; +typedef REMOTE_UPDATE_USER_RESP *P_REMOTE_UPDATE_USER_RESP; ///< pointer to ::REMOTE_UPDATE_USER_RESP type + +/** +\ingroup xnodus_remote_cmd +Create or update a user remotely. + +Construct a remote command buffer to perform the same task of the xnd_create_user() or xnd_update_user() functions. +\param[in] dev_ctx an administrator device context object handle. +\param[in] cmd points to a structure ::REMOTE_UPDATE_USER_CMD with the arguments of the command. +\param[out] enc_cmd points to a buffer that will receive the command buffer to be remotely applied to the device using xnd_apply_remote_command(). +\param[in] enc_cmd_size the size of the buffer pointed by 'enc_cmd'. +\param[out] p_enc_cmd_len points to an unsigned integer that will receive the length of the command pointed by 'enc_cmd'. +\return ::XND_ERROR_SUCCESS if found, an \ref xnodus_errors "error code" on failure. +\remark To apply the command to the xNodus device it is necessary run xnd_apply_remote_command() in an application that can communicate directly to the target xNodus device. As input it needs the generated encrypted command +(i.e. the result pointed by enc_cmd). If it is necessary to know the result of the operation of xnd_apply_remote_command(), the function xnd_remote_resp_update_user() can analyze the response to the command. +\see xnd_remote_resp_update_user(), xnd_apply_remote_command(). +*/ +XND_LINK int XND_API xnd_remote_cmd_update_user(XND_DEVICE_CONTEXT dev_ctx, const REMOTE_UPDATE_USER_CMD* cmd, OUT unsigned char* enc_cmd, unsigned int enc_cmd_size, OUT unsigned int* p_enc_cmd_len); + +/** +\ingroup xnodus_remote_cmd + +Retrieve the status of a remote 'user create or update' command. +\param[in] dev_ctx an administrator device context object handle. +\param[in] enc_resp points to a buffer containing the response of xNodus returned by the function xnd_apply_remote_command(). +\param[in] enc_resp_len the length of the buffer pointed by 'enc_resp'. +\param[out] p_resp points to a struct of type ::REMOTE_UPDATE_USER_RESP that will be filled with the status and data of the remote operation. +\return ::XND_ERROR_SUCCESS if found, an \ref xnodus_errors "error code" on failure. + +\see xnd_remote_cmd_update_user(), xnd_apply_remote_command(). +*/ +XND_LINK int XND_API xnd_remote_resp_update_user(XND_DEVICE_CONTEXT dev_ctx, const unsigned char* enc_resp, unsigned int enc_resp_len, OUT P_REMOTE_UPDATE_USER_RESP p_resp); + +/** +Delete user command structure for remote command + +This is the structure of the remote 'delete user' (see xnd_delete_user()). +In order to perform a remote 'delete user' it is necessary set the serial number (just the final four bytes of the sixteen overall) +and set a counter greater than the current one. Both values are returned by xnd_get_info(). + +It is suggested to use the unix time for destination_counter: this allow to avoid to read its value and grant to use a value +greater than the previous one +*/ +typedef struct _REMOTE_DELETE_USER_CMD { + XND_USER_NAME user_name; ///< User to be deleted + unsigned char destination_serial_part[4];///< final four bytes of the xNodus device serial number (XND_INFO.sn). + unsigned int destination_counter; ///< counter of the operation (must be grater than XND_INFO.remote_counter). +}REMOTE_DELETE_USER_CMD; +typedef REMOTE_DELETE_USER_CMD *P_REMOTE_DELETE_USER_CMD; ///< pointer to ::REMOTE_DELETE_USER_CMD type + +/** +Delete user response structure for remote command + +This is the structure of the remote delete user answer. It contains the argument of the command and the status of the operation +*/ +typedef struct _REMOTE_DELETE_USER_RESP { + REMOTE_DELETE_USER_CMD issued_cmd; ///< arguments of the 'delete user' command sent to the device + int status; ///< the status of the operation returned by the device +}REMOTE_DELETE_USER_RESP; +typedef REMOTE_DELETE_USER_RESP *P_REMOTE_DELETE_USER_RESP; ///< pointer to ::REMOTE_DELETE_USER_RESP type + +/** +\ingroup xnodus_remote_cmd +Delete a user remotely. + +Construct a remote command buffer to perform the same task of the xnd_delete_user(). +\param[in] dev_ctx an administrator device context object handle. +\param[in] cmd points to a structure ::REMOTE_DELETE_USER_CMD with the arguments of the command. +\param[out] enc_cmd points to a buffer that will receive the command buffer to be remotely applied to the device using xnd_apply_remote_command(). +\param[in] enc_cmd_size the size of the buffer pointed by 'enc_cmd'. +\param[out] p_enc_cmd_len points to an unsigned integer that will receive the length of the command pointed by 'enc_cmd'. +\return ::XND_ERROR_SUCCESS if found, an \ref xnodus_errors "error code" on failure. +\remark To apply the command to the xNodus device it is necessary run xnd_apply_remote_command() in an application that can communicate directly to the target xNodus device. As input it needs the generated encrypted command +(i.e. the result pointed by enc_cmd). If it is necessary to know the result of the operation of xnd_apply_remote_command(), the function xnd_remote_resp_delete_user() can analyze the response to the command. +\see xnd_remote_resp_delete_user(), xnd_apply_remote_command(). +*/ +XND_LINK int XND_API xnd_remote_cmd_delete_user(XND_DEVICE_CONTEXT dev_ctx, const REMOTE_DELETE_USER_CMD* cmd, OUT unsigned char* enc_cmd, unsigned int enc_cmd_size, OUT unsigned int* p_enc_cmd_len); + +/** +\ingroup xnodus_remote_cmd + +Retrieve the status of a remote 'delete user' command. +\param[in] dev_ctx an administrator device context object handle. +\param[in] enc_resp points to a buffer containing the response of xNodus returned by the function xnd_apply_remote_command(). +\param[in] enc_resp_len the length of the buffer pointed by 'enc_resp'. +\param[out] p_resp points to a struct of type ::REMOTE_DELETE_USER_RESP that will be filled with the status and data of the remote operation. +\return ::XND_ERROR_SUCCESS if found, an \ref xnodus_errors "error code" on failure. + +\see xnd_remote_cmd_delete_user(), xnd_apply_remote_command(). +*/ +XND_LINK int XND_API xnd_remote_resp_delete_user(XND_DEVICE_CONTEXT dev_ctx, const unsigned char* enc_resp, unsigned int enc_resp_len, OUT P_REMOTE_DELETE_USER_RESP p_resp); + +/** +\ingroup xnodus_remote_cmd +Apply a remote command. +\param[in] dev_ctx a ::XND_DEVICE_CONTEXT handle referring to a device context object where the session state (open or not) is irrelevant. +\param[in] send_buf points to a buffer containing the encrypted remote commmand. +\param[in] send_len the length in bytes of the buffer pointed by 'send_buf'. +\param[out] p_recv_len points to an unsigned integer that will receive the length of the returned response. +\param[in] recv_timeout_ms timeout in millisecond of the operation. If this value is set to '0' a default value is taken. +\param[out] p_ret_status points to an integer receiving the inner status of the executed command: ::XND_ERROR_SUCCESS on success, an \ref xnodus_errors "error code" on failure. +\return return a buffer that containing the encrypted response to the command. +\remark The buffer returned by the function must be freed calling xnd_free(). +*/ +XND_LINK unsigned char* XND_API xnd_apply_remote_command(XND_DEVICE_CONTEXT dev_ctx, const unsigned char* send_buf, unsigned int send_len, OPT unsigned int recv_timeout_ms, OUT unsigned int* p_recv_len, OUT int* p_ret_status); + +/** +\defgroup xnd_log_mask xNodus Log mask +\ingroup xnodus_defines + +Mask values for the information to retrieve by the log functions (see \ref xnd_get_log_list_start()) +These mask values are used as significant bit mask also in the field set_values_mask of the structure ::XND_LOG_DATA +@{ +*/ +#define XND_LOG_SIGNIFICANT_MASK_LICENSE_ID_HASH 0x00000001 ///< license_id_hash entry in ::XND_LOG_DATA is significant +#define XND_LOG_SIGNIFICANT_MASK_OPEN_INSTANCES 0x00000002 ///< num_open_instances entry in ::XND_LOG_DATA is significant +#define XND_LOG_SIGNIFICANT_MASK_USER_IDX 0x00000004 ///< user_idx entry in ::XND_LOG_DATA is significant +#define XND_LOG_SIGNIFICANT_MASK_USER_NAME 0x00000008 ///< user_name entry in ::XND_LOG_DATA is significant +#define XND_LOG_SIGNIFICANT_MASK_CLIENT_IP 0x00000010 ///< ip_addr entry in ::XND_LOG_DATA is significant +#define XND_LOG_SIGNIFICANT_MASK_OPEN_MODULES 0x00000020 ///< open_modules entry in ::XND_LOG_DATA is significant +//@} //xnd_log_mask + +/** +\ingroup xnodus_defines +minimum information data mask that can be retrieved by the log functions +*/ +#define XND_LOG_MASK_MIN (XND_LOG_SIGNIFICANT_MASK_LICENSE_ID_HASH | XND_LOG_SIGNIFICANT_MASK_OPEN_INSTANCES) + +/** +\ingroup xnodus_defines +complete information data mask that can be retrieved by the log functions +*/ +#define XND_LOG_SIGNIFICANT_MASK_ALL (XND_LOG_SIGNIFICANT_MASK_LICENSE_ID_HASH | XND_LOG_SIGNIFICANT_MASK_OPEN_INSTANCES | \ + XND_LOG_SIGNIFICANT_MASK_USER_IDX | XND_LOG_SIGNIFICANT_MASK_USER_NAME | XND_LOG_SIGNIFICANT_MASK_CLIENT_IP | XND_LOG_SIGNIFICANT_MASK_OPEN_MODULES) + +/** +\ingroup xnodus_defines +Length of the License identifier value inside the structure ::XND_LOG_DATA +*/ +#define XND_LOG_ID_HASH_LEN 4 + +/** +\ingroup xnodus_log +Log structure, +Description of the status of a given using license instance. +In case multi-instance (see \ref xnd_users_group_lic) is not used this values represent the data of an open session, in case +of multi-instance usage it collects the description of the sum of the session that are using a specific license instance. + +The entry num_open_instances counts the number of session referring to the license instance. + +*/ +typedef struct _XND_LOG_DATA{ + unsigned int set_values_mask;///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 xlt_Errors "error code" on failure. + The user must not rely on this number to infer the order of insertion or the physical position of an XLight device in the USB HUB of the host computer. + +\par Example + \code + #include "xnd.h" + #include + + ... + + int status; + unsigned int version; + unsigned int model; + unsigned int flags; + unsigned int serial; + unsigned char label_printable[XLT_LABEL_SIZE + 1]; + int i; + unsigned int device; + XND_DEVICE_CONTEXT dev_ctx = 0; + XND_XLT_ENV env = xnd_xlt_env_create(); + if (!env){ + printf("An error has occurred running xnd_xlt_env_create()!\n"); + goto end; + } + + for(device = 0; device < XLT_DEVICE_MAX; device++){ + dev_ctx = xnd_xlt_devctx_xlight_create(env, device, 0, 0, &status); + if (status != XND_ERROR_SUCCESS){ + //this shouldn't happen! + printf("Error running xnd_xlt_devctx_xlight_create() - error code: %d\n", status); + goto end; + } + + status = xnd_xlt_getinfo(dev_ctx, &version, &model, &flags, &serial, label_printable); + if (status == XLT_ERROR_NOT_FOUND) + printf("Device not found at index %d!\n", device); + else if (status != XLT_ERROR_SUCCESS) + printf("An error has occurred!\n"); + else { + printf("An XLight device was found plugged into the logical port %d\n", device); + printf("Version: %x.%02x\n", version >> 8, version & 0xFF); + if (model != XLT_MODEL_BASIC_USBHID) + printf("Unrecognized model!\n"); + if (flags & XLT_FLAG_SETUP){ + printf("The device is initialized\n"); + for(i = 0; i < XLT_NUMBER_OF_BANKS; i++){ + if (flags & (XLT_FLAG_FROZEN_BANK0 << i)) + printf("Bank %d frozen\n", i); + } + } + else + printf("The device is NOT initialized\n"); + + printf("The device Serial Number is: 0x%x\n", serial); + label_printable[XLT_LABEL_SIZE] = 0; + //N.B.: a label may contain not printable character + printf("Label: %s\n", (char*) label_printable); + } + xnd_xlt_devctx_release(dev_ctx); + dev_ctx = 0; + } + ... +end: + xnd_xlt_devctx_release(dev_ctx); + xnd_xlt_env_free(env); + ... +\endcode + + */ +XND_LINK int XND_API xnd_xlt_getinfo(XND_DEVICE_CONTEXT dev_ctx, unsigned int* pversion, unsigned int* pmodel, unsigned int* pflags, unsigned int* pserial, unsigned char* label); + + +/** +\ingroup xnd_xlt_device +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] dev_ctx ::XND_DEVICE_CONTEXT handle referring to the selected device. +\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 xnd_xlt_session_wrap_key() and xnd_xlt_rsa_wrap_privkey(). +\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 function xnd_xlt_challenge(). +\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 with cryptography +that uses Dongle Key as the base to wrap the \ref xn_RSA_Protection "RSA" and \ref xn_AES_Session_Key "AES session" keys which constitutes the key point of the software protection. + +\parblock +\note before calling xnd_xlt_setup() a device is in a non initialized state. In this context only the function xnd_xlt_getinfo() works. +\endparblock +\parblock +\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. +\endparblock +\parblock +\note Never put xnd_xlt_setup() inside the protected application as well: this function can be called from some initialization code used in +safe environment. If you don't need to manage special setup procedure you can avoid to use this function and rely on the utilities supplied by OxySec. +\endparblock + +\par Example +In the code below the function GetFirstXLightDeviceContext() comes from \ref GetFirstXLightDeviceContext "this example". +\code +#include +#include "xnd.h" + +void xlight_setup_example() +{ + + int status; + unsigned char label[XLT_LABEL_SIZE]; + unsigned char password[XLT_PASSWORD_SIZE]; + unsigned char dongle_key[XLT_KEY_SIZE]; + unsigned char challenge_response_key[XLT_KEY_SIZE]; + XND_XLT_ENV env = xnd_xlt_env_create(); + XND_DEVICE_CONTEXT dev_ctx = 0; + + + //xnd_xlt_setup set label, password, user and challenge response keys (dongle_key and challenge_response_key) once for all. + //Only label must be specified, but it is strongly recommeded to set password, dongle_key, challenge_response_key as well + //with non trivial (random) values and keep them secret. + + //BEWARE: label, password, dongle_key and challenge_response_key are not strings but arrays, + //so fill them up to their entire size + + strcpy((char*)label, "My XLight label"); + memset(label + strlen("My XLight label"), 0x00, sizeof(label) - strlen("My XLight label")); + + //set password + ... + + //set dongle_key + ... + + //set challenge_response_key + ... + + //GetFirstXLightDeviceContext() comes from an example of the XNodus documentation + dev_ctx = GetFirstXLightDeviceContext(env); + if (!dev_ctx){ + printf("An error occurred (probably no XLight device was found"); + goto end; + } + + status = xnd_xlt_setup(dev_ctx, label, password, dongle_key, challenge_response_key); + if (status != XLT_ERROR_SUCCESS){ + printf("An error has occurred running xnd_xlt_setup(): error code = %d\n", status); + if (status == XLT_ERROR_INVALID_STATE){ + printf("Probably the device is already programmed!\n"); + } + goto end; + } + printf("XLight device correctly initialized.\n"); + + //... +end: + xnd_xlt_devctx_release(dev_ctx); + xnd_xlt_env_free(env); +} +\endcode + +*/ +XND_LINK int XND_API xnd_xlt_setup(XND_DEVICE_CONTEXT dev_ctx, const unsigned char* label, const unsigned char* password, const unsigned char* dongle_key, const unsigned char* cr_key); + +/** +\ingroup xnd_xlt_bank +Write into a memory bank of the XLight device. +\param[in] dev_ctx ::XND_DEVICE_CONTEXT handle referring to the selected device. +\param[in] password points to a buffer of length ::XLT_PASSWORD_SIZE that contains the password assigned to the device. +\param[in] bank the index of the memory bank that must be written. +\param[in] data points to a buffer of size ::XLT_BANK_SIZE containing the data to be written into the memory. +\return returns ::XLT_ERROR_SUCCESS on success, an \ref xlt_Errors "error code" on failure. +\remark The password entry must be the same that was used in xnd_xlt_setup() call. If it was NULL, it must be NULL also in xnd_xlt_write(). + +\par Example +In the code below the function GetFirstXLightDeviceContext() comes from \ref GetFirstXLightDeviceContext "this example". +\code {.c} +void xlight_write_example() +{ + int status; + unsigned char password[XLT_PASSWORD_SIZE]; + unsigned char data[XLT_BANK_SIZE]; + XND_XLT_ENV env = xnd_xlt_env_create(); + XND_DEVICE_CONTEXT dev_ctx = 0; + + //GetFirstXLightDeviceContext() comes from an example of the XNodus documentation + dev_ctx = GetFirstXLightDeviceContext(env); + if (!dev_ctx){ + printf("An error occurred (probably no XLight device was found"); + goto end; + } + + //BEWARE: data, is not a not string but an array, + //so fill it up to its entire size + strcpy((char*)data, "Some data"); + memset(data + strlen("Some data"), 0x00, sizeof(data) - strlen("Some data")); + + //Of course you will use a more secure password than 'My XLight password' use in this example! + 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 = xnd_xlt_write(dev_ctx, password, 0, data); + if (status != XLT_ERROR_SUCCESS){ + printf("An error has occurred.\n"); + goto end; + } + //... +end: + xnd_xlt_devctx_release(dev_ctx); + xnd_xlt_env_free(env); +} +\endcode + +*/ +XND_LINK int XND_API xnd_xlt_write(XND_DEVICE_CONTEXT dev_ctx, const unsigned char* password, unsigned int bank, const unsigned char* data); + +/** +\ingroup xnd_xlt_bank +Read from a memory bank of the XLight device. +\param[in] dev_ctx ::XND_DEVICE_CONTEXT handle referring to the selected device. +\param[in] password points to a buffer of length ::XLT_PASSWORD_SIZE that contains the password assigned to the device. +\param[in] bank the index of the memory bank that must be read. +\param[out] data points to a buffer of size ::XLT_BANK_SIZE that will receive the data read from the adressed memory bank. +\return returns ::XLT_ERROR_SUCCESS on success, an \ref xlt_Errors "error code" on failure. +\remark The password entry must be the same that was used in xnd_xlt_setup() call. If it was NULL, it must be NULL also in xnd_xlt_read(). + +\par Example +In the code below the function GetFirstXLightDeviceContext() comes from \ref GetFirstXLightDeviceContext "this example". +\code {.c} +void xlight_read_example() +{ + int status; + unsigned char password[XLT_PASSWORD_SIZE]; + unsigned char data[XLT_BANK_SIZE]; + XND_XLT_ENV env = xnd_xlt_env_create(); + XND_DEVICE_CONTEXT dev_ctx = 0; + + //GetFirstXLightDeviceContext() comes from an example of the XNodus documentation + dev_ctx = GetFirstXLightDeviceContext(env); + if (!dev_ctx){ + printf("An error occurred (probably no XLight device was found"); + goto end; + } + + 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 = xnd_xlt_read(dev_ctx, password, 0, data); + if (status != XLT_ERROR_SUCCESS){ + printf("An error has occurred.\n"); + } + else { + //N.B.: the data banks may contain not printable character + //(and in general it makes no sense print out memory content, this is just an example) + printf("Bank 0 data: %s\n", (char*)data); + } +end: + xnd_xlt_devctx_release(dev_ctx); + xnd_xlt_env_free(env); +} +\endcode +*/ +XND_LINK int XND_API xnd_xlt_read(XND_DEVICE_CONTEXT dev_ctx, const unsigned char* password, unsigned int bank, unsigned char* data); + +/** +\ingroup xnd_xlt_bank +Lock a memory bank. + +\note This function produces an irreversible setting onto the XLight device, hence use it very carefully. + +See \ref xn_locked_memory. +\param[in] dev_ctx ::XND_DEVICE_CONTEXT handle referring to the selected device. +\param[in] password points to a buffer of length ::XLT_PASSWORD_SIZE. It contains the password assigned to the device with xnd_xlt_setup(). +\param[in] bank the index of the memory bank that must be locked. +\param[in] group_number the group number to be assigned to the locking bank. +\return returns ::XLT_ERROR_SUCCESS on success, an \ref xlt_Errors "error code" on failure. + +A locked memory bank can be written only using encrypted commands created by xnd_xlt_set_write_locked_group_check() or xnd_xlt_set_write_locked_serial_check() +and performed by xnd_xlt_write_locked(). +\note the group number is intended to define subgroups that must be treated in different ways. If there is no reason to create such differentiation +it must be inserted the same number for all devices, say 0. +The grouping allows to create a single encrypted command to modify the memory content of locked banks onto a large number of devices. + +\remark it is not useful to set a different group number for every device because it is already possible create a command for a single device by using its serial number. + +\note a locked bank can always be read using the xnd_xlt_read() function, but can't be written with xnd_xlt_write() any more. +A locked memory bank is subject to a restriction in its dimension: only ::XLT_LOCKED_BANK_DATA_LENGTH will be freely available for reading and writing. +The remaining bytes are used by the locking mechanism management. + +\sa xnd_xlt_bank_lock2(), xnd_xlt_set_write_locked_group_check(), xnd_xlt_set_write_locked_serial_check() + +*/ +XND_LINK int XND_API xnd_xlt_bank_lock(XND_DEVICE_CONTEXT dev_ctx, const unsigned char* password, unsigned int bank, unsigned int group_number); + +/** +\ingroup xnd_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 xn_locked_memory. +\param[in] dev_ctx ::XND_DEVICE_CONTEXT handle referring to the selected device. +\param[in] password points to a buffer of length ::XLT_PASSWORD_SIZE. It contains the password assigned to the device with xnd_xlt_setup(). +\param[in] bank the index of the memory bank that must be locked. +\param[in] group_number the group number to be assigned to the locking bank. +\return returns ::XLT_ERROR_SUCCESS on success, an \ref xlt_Errors "error code" on failure. + +A locked2 memory bank can be written only using encrypted commands created by xnd_xlt_set_write_locked2_group_check() or xnd_xlt_set_write_locked2_serial_check() +and performed by xnd_xlt_write_locked(). +\note the group number is intended to define subgroups that must be treated in different ways. If there is no reason to create such differentiation +it must be inserted the same number for all devices, say 0. +The grouping allows to create a single encrypted command to modify the memory content of locked banks onto a large number of devices. + +\remark it is not useful to set a different group number for every device because it is already possible create a command for a single device by using its serial number. + +\note a locked bank can always be read using the xnd_xlt_read() function, but can't be written with xnd_xlt_write() any more. +A locked2 memory bank is subject to a restriction in its dimension: only ::XLT_LOCKED_BANK_DATA_LENGTH will be freely available for reading and writing. +The remaining bytes are used by the locking mechanism management. +

      Supported version: this function is available on XLight devices version 1.01 or later. +\see xnd_xlt_set_write_locked2_group_check(), xnd_xlt_set_write_locked2_serial_check() +*/ +XND_LINK int XND_API xnd_xlt_bank_lock2(XND_DEVICE_CONTEXT dev_ctx, const unsigned char* password, unsigned int bank, unsigned int group_number); + +/** +\ingroup xnd_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] dev_ctx ::XND_DEVICE_CONTEXT handle referring to the selected device. +\param[in] password points to a buffer of length ::XLT_PASSWORD_SIZE that contains the password assigned to the device. +\param[in] bank the index of the memory bank that must be frozen. +\return returns ::XLT_ERROR_SUCCESS on success, an \ref xlt_Errors "error code" on failure. +\remark The password entry must be the same that was used in xnd_xlt_setup() call. If it was NULL, it must be NULL also in xnd_xlt_bank_freeze(). + +\par Example +In the code below the function GetFirstXLightDeviceContext() comes from \ref GetFirstXLightDeviceContext "this example". +\code{.c} +void xlight_freeze_example() +{ + int status; + unsigned char password[XLT_PASSWORD_SIZE]; + XND_XLT_ENV env = xnd_xlt_env_create(); + XND_DEVICE_CONTEXT dev_ctx = 0; + + //GetFirstXLightDeviceContext() comes from an example of the XNodus documentation + dev_ctx = GetFirstXLightDeviceContext(env); + if (!dev_ctx){ + printf("An error occurred (probably no XLight device was found"); + goto end; + } + + strcpy((char*)password, "My XLight password"); + memset(password + strlen("My XLight password"), 0x00, sizeof(password) - strlen("My XLight password")); + + //freeze the bank 0 of an XLight dongle + //BEWARE: after the freeze the memory content of the bank 0 can't be modified any longer + status = xnd_xlt_bank_freeze(dev_ctx, password, 0); + if (status != XLT_ERROR_SUCCESS){ + printf("An error has occurred.\n"); + if (status == XLT_ERROR_FROZEN){ + printf("The device was already frozen.\n"); + } + } + +end: + xnd_xlt_devctx_release(dev_ctx); + xnd_xlt_env_free(env); +} +\endcode + +*/ +XND_LINK int XND_API xnd_xlt_bank_freeze(XND_DEVICE_CONTEXT dev_ctx, const unsigned char* password, unsigned int bank); + +/** +\deprecated +This function is deprecated because substituted by the more effective \ref xn_AES_Session_Key "session encryption". + +Perform AES-256 encryption + \param[in] dev_ctx ::XND_DEVICE_CONTEXT handle referring to the selected device. + \param[in] plaintext points to the buffer of length ::XLT_CIPHERTEXT_SIZE containing the plaintext to encrypt. + \param[out] ciphertext points to the buffer of length ::XLT_CIPHERTEXT_SIZE receiving the encrypted result. + \return returns ::XLT_ERROR_SUCCESS on success, an \ref xlt_Errors "error code" on failure. + \note The encryption function uses as cryptographic key the Dongle Key entry set by xnd_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 processes as discussed in xnd_xlt_challenge() documentation. +*/ +XND_LINK int XND_API xnd_xlt_encrypt(XND_DEVICE_CONTEXT dev_ctx, const unsigned char* plaintext, unsigned char* ciphertext); + +/** +\deprecated +This function is deprecated because substituted by the more effective \ref xn_AES_Session_Key "session encryption". + +Perform AES-256 decryption. + \param[in] dev_ctx ::XND_DEVICE_CONTEXT handle referring to the selected device. + \param[in] ciphertext points to the buffer of length ::XLT_CIPHERTEXT_SIZE containing the ciphertext to be decrypted. + \param[out] plaintext points to the buffer of length ::XLT_CIPHERTEXT_SIZE containing the result of the decryption. + \return returns ::XLT_ERROR_SUCCESS on success, an \ref xlt_Errors "error code" on failure. + \remark This function is the inverse of xnd_xlt_encrypt(), that is from ciphertext it returns the original plaintext passed to xnd_xlt_encrypt(). + \note The decryption function uses as cryptographic key the Dongle Key entry set by xnd_xlt_setup(). +*/ +XND_LINK int XND_API xnd_xlt_decrypt(XND_DEVICE_CONTEXT dev_ctx, const unsigned char* ciphertext, unsigned char* plaintext); + +/** +\deprecated +This function is deprecated because substituted by the more effective \ref xn_AES_Session_Key "session encryption". + +Challenge-Response computation based on AES-256. +The protected software send a value and check that the outcome is as expected. + \param[in] dev_ctx ::XND_DEVICE_CONTEXT handle referring to the selected device. + \param[in] challenge points to the buffer of length ::XLT_CIPHERTEXT_SIZE containing the challenge data. + \param[out] response points to the buffer of length ::XLT_CIPHERTEXT_SIZE receiving the response. + \return returns ::XLT_ERROR_SUCCESS on success, an \ref xlt_Errors "error code" on failure. + \note The Challenge-Response mechanism uses as cryptographic key the cr_key (Challenge Response Key) entry set by xnd_xlt_setup(). + \remark The challenge response mechanism is a sort of proof of identity without exposing details to eavesdroppers on the USB communication or + on the dll interface. It is based onto the AES-256 encryption and the verifier inside the protected program must know the key used by the + device. A good hacker debugging the code can come up to the encryption key, so the best policy is to make this task hard trying to hide + the key: for instance preparing the challenge and evaluating the response far from the code communicating with the dongle. The example below is not a good + example from this point of view and it must be considered just as an example. xnd_xlt_challenge() works in the same way of xnd_xlt_encrypt() but using a different AES key. + + \note Another possible and better way is to calculate many pairs challenge-presponse in a safe environment (i.e. not in the protected application) + and use such pairs to verify the response of the dongle. This method avoid the exposure of the Challenge Response Key. +*/ +XND_LINK int XND_API xnd_xlt_challenge(XND_DEVICE_CONTEXT dev_ctx, const unsigned char* challenge, unsigned char* response); + +/** +\ingroup xnd_xlt_aes +Load on an XLight device the session AES key to be used for AES session encryption functions. +See \ref xn_AES_Session_Key for an introduction on Session Key protection. + + \param[in] dev_ctx ::XND_DEVICE_CONTEXT handle referring to the selected device. + \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 xlt_Errors "error code" on failure. + + This function must be used to set the AES key that will be used by xnd_xlt_session_encrypt() and xnd_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 xnd_xlt_session_wrap_key(). + It is possible to set ::XLT_SESSION_NUMBER_OF_KEYS sessin key simultaneously, with key_index it is possible to refer to one of these keys. + + \note a Session Key is not permanent, it resides on the device as long as the dongle is plugged and powered, once the dongle is + removed the key is deleted. This means that it must be loaded every time it must be used. The default value, that is just after the device is plugged, + is a zero buffer. +See \ref xn_Session_KeyProtection "here" for a source code example using this function. +

      Supported version: this function is available on XLight devices version 2.0 or later. +\see xnd_xlt_session_encrypt(), xnd_xlt_session_decrypt(), xnd_xlt_session_wrap_key(). +*/ +XND_LINK int XND_API xnd_xlt_session_set_key(XND_DEVICE_CONTEXT dev_ctx, unsigned int key_index, const unsigned char* wrapped_key); + +/** +\ingroup xnd_xlt_aes +Encrypt data using a Session Key. +See \ref xn_AES_Session_Key for an introduction on Session Key protection. + \param[in] dev_ctx ::XND_DEVICE_CONTEXT handle referring to the selected device. + \param[in] key_index index of the key to be used. This value runs from 0 to ::XLT_SESSION_NUMBER_OF_KEYS -1. + \param[in] plaintext points to the buffer of length ::XLT_CIPHERTEXT_SIZE containing the data to be encrypted + \param[out] ciphertext points to the buffer of length ::XLT_CIPHERTEXT_SIZE that will receive the encrypted data. + \return returns ::XLT_ERROR_SUCCESS on success, an \ref xlt_Errors "error code" on failure. + + This function performs AES-256 encryption of a plaintext of length ::XLT_CIPHERTEXT_SIZE and inserts the ciphertext result in a buffer of the same length. + The AES key is one of the eight Session Keys specified by the index key_index, and the corrisponding key was previously set by the xnd_xlt_session_decrypt() function. + + See \ref xn_Session_KeyProtection "here" for a source code example using this function. +

      Supported version: this function is available on XLight devices version 2.0 or later. + \see xnd_xlt_session_decrypt(), xnd_xlt_session_set_key(), xnd_xlt_session_wrap_key(). +*/ +XND_LINK int XND_API xnd_xlt_session_encrypt(XND_DEVICE_CONTEXT dev_ctx, unsigned int key_index, const unsigned char* plaintext, unsigned char* ciphertext); + +/** +\ingroup xnd_xlt_aes +Decrypt data using a Session Key. +See \ref xn_AES_Session_Key for an introduction on Session Key protection. + \param[in] dev_ctx ::XND_DEVICE_CONTEXT handle referring to the selected device. + \param[in] key_index index of the key to be used. This value runs from 0 to ::XLT_SESSION_NUMBER_OF_KEYS -1. + \param[in] ciphertext points to the buffer of length ::XLT_CIPHERTEXT_SIZE containing the data to be decrypted. + \param[out] plaintext points to the buffer of length ::XLT_CIPHERTEXT_SIZE that will receive the decrypted data. + \return returns ::XLT_ERROR_SUCCESS on success, an \ref xlt_Errors "error code" on failure. + + This function performs AES-256 decryption of a ciphertext buffer with length of the block of the AES algorithm, that is a length of ::XLT_CIPHERTEXT_SIZE. + The used key was set by a previous call of xnd_xlt_session_set_key(). +

      Supported version: this function is available on XLight devices version 2.0 or later. + \see xnd_xlt_session_encrypt(), xnd_xlt_session_set_key(), xnd_xlt_session_wrap_key(). +*/ +XND_LINK int XND_API xnd_xlt_session_decrypt(XND_DEVICE_CONTEXT dev_ctx, unsigned int key_index, const unsigned char* ciphertext, unsigned char* plaintext); + +/** +\ingroup xnd_xlt_aes +Wraps a Session Key. +See \ref xn_AES_Session_Key for an introduction on Session Key protection. + \param[in] dev_ctx ::XND_DEVICE_CONTEXT handle referring to a real or fake device. + \param[in] key points to the AES key that will be used by xnd_xlt_session_encrypt() and xnd_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 xnd_xlt_setup() function. + \param[out] wrapped_key points to a memory buffer of length ::XLT_KEY_SIZE that will receive the wrapped version of key. +\return returns ::XLT_ERROR_SUCCESS on success, an \ref xlt_Errors "error code" on failure. + +\note Never use this function onto the protected software, in particular, never insert the 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 +final user. The Wrapped Key must be used onto the protected software and loaded onto the XLight dongle using xnd_xlt_session_set_key(). + +See \ref xn_Session_KeyPreliminary "here" for a source code example using this function. + +

      Supported version: this function is available on XLight devices version 2.0 or later. + +\sa xnd_xlt_session_set_key(). +*/ +XND_LINK int XND_API xnd_xlt_session_wrap_key(XND_DEVICE_CONTEXT dev_ctx, const unsigned char* key, const unsigned char* dongle_key, unsigned char* wrapped_key); + +/** +\ingroup xnd_xlt_rsa +Generate an RSA key. +See \ref xn_RSA_Protection for an introduction on the RSA protection in XLight. +\param[in] dev_ctx ::XND_DEVICE_CONTEXT handle referring to a real or fake device. +\param[in] bit_size the length in bit of the key to generate. The possible values are ::XLT_RSA_512_BIT_SIZE and ::XLT_RSA_1024_BIT_SIZE. +\param[out] private_key points to the buffer that will receive the generated RSA private key formatted with XLight RSA Key format (\ref xn_RSA_format). +\param[in] private_key_size size of the private_key buffer. The size for a 1024 bit key is ::XLT_RSA_1024_PRIV_KEY_SIZE and the size for a 512 bit key is ::XLT_RSA_512_PRIV_KEY_SIZE. +\param[out] p_private_key_len points to an unsigned integer that will receive the actual length of the generated formatted private key. +\param[out] public_key points to the buffer that will receive the generated RSA public key formatted in XLight RSA Key format (\ref xn_RSA_format). +If this parameter is NULL the public key is not retrieved. +\param[in] public_key_size size of the public_key buffer. The size for a 1024 bit key is ::XLT_RSA_1024_PUB_KEY_SIZE and the size for a 512 bit key is ::XLT_RSA_512_PUB_KEY_SIZE. +\param[out] p_public_key_len points to an unsigned integer that will receive the actual length of the generated formatted public key. +\return ::XLT_ERROR_SUCCESS on success, an \ref xlt_Errors "error code" on failure. + +\note This is an utility function that must be never used onto the protected software. Its purpose is RSA key generation and may be substituted +by other software doing the same task. There are plenty of source code available in internet doing RSA key generation. +

      Supported version: this function is available on XLight devices version 2.0 or later. +\sa xnd_xlt_rsa_wrap_privkey(). +*/ +XND_LINK int XND_API xnd_xlt_rsa_generate_key(XND_DEVICE_CONTEXT dev_ctx, unsigned int bit_size, unsigned char* private_key, unsigned int private_key_size, unsigned int* p_private_key_len, unsigned char* public_key, unsigned int public_key_size, unsigned int* p_public_key_len); + +/** +\ingroup xnd_xlt_rsa +Wraps an RSA key. +See \ref xn_RSA_Protection for an introduction on the RSA protection in XLight. +\param[in] dev_ctx ::XND_DEVICE_CONTEXT handle referring to a real or fake device. +\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 xn_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 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 xnd_xlt_rsa_set_privkey(). +\sa xnd_xlt_rsa_set_privkey() +*/ +XND_LINK int XND_API xnd_xlt_rsa_wrap_privkey(XND_DEVICE_CONTEXT dev_ctx, 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 xnd_xlt_rsa +Wraps an RSA key. +As xnd_xlt_rsa_wrap_privkey() function but with the addition to bind a specific recipient XLight device by its serial number. +See \ref xn_RSA_Protection for an introduction on the RSA protection in XLight. +\param[in] dev_ctx ::XND_DEVICE_CONTEXT handle referring to a real or fake device. +\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 xn_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 xnd_xlt_rsa_set_privkey(). + +

      Supported version: this function is available on XLight devices version 2.4 or later. +\sa xnd_xlt_rsa_wrap_privkey() +*/ +XND_LINK int XND_API xnd_xlt_rsa_wrap_privkey_sn(XND_DEVICE_CONTEXT dev_ctx, 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 xnd_xlt_rsa +Load an RSA private key onto an XLight device. +See \ref xn_RSA_Protection for an introduction on the RSA protection in XLight. +\param[in] dev_ctx ::XND_DEVICE_CONTEXT handle referring to the selected device. +\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 xlt_Errors "error code" on failure. + +\note on an XLight device it is possible to store two RSA keys: one 1024 bit key and one 512 bit key. The bit length reppresent the length of its +"modulus", not the length of the data containing the key (see \ref RSA_format). The device recognizes the two different key types and write them in their reserved memory place. + +The RSA key received from this function is not in clear form, but encrypted by the function xnd_xlt_rsa_wrap_privkey(). +In this way the RSA private key can be set by the protected program without exposing any relevant data, and hence preventing a hacker to understand the values (which would ruin all the security protocol based on RSA). + +\note an RSA key is present onto the device also after device removal because it is written in a non volatile memory, +nevertheless it can be always overwritten with a new one. +

      Supported version: this function is available on XLight devices version 2.0 or later. +\see xnd_xlt_rsa_wrap_privkey(). +*/ +XND_LINK int XND_API xnd_xlt_rsa_set_privkey(XND_DEVICE_CONTEXT dev_ctx, const unsigned char* wrapped_key, unsigned int wrapped_key_length); + +/** +\ingroup xnd_xlt_rsa +Performs RSA encryption. +\deprecated just use for test purpose + +See \ref xn_RSA_Protection for an introduction on the RSA protection in XLight. +\param[in] dev_ctx ::XND_DEVICE_CONTEXT handle referring to a real or fake device. +\param[in] public_key points to the buffer containing the formatted public key used for the encryption. +\param[in] public_key_len length of the formatted public key. The allowed values are ::XLT_RSA_1024_PUB_KEY_SIZE and ::XLT_RSA_512_PUB_KEY_SIZE. +\param[in] plaintext points to the buffer containing the data to be encrypted. +\param[in] plaintext_ciphertext_length the length of plaintext and the size of the buffer pointed by ciphertext. +The allowed values for this argument are ::XLT_RSA_1024_PLAINTEXT_SIZE and ::XLT_RSA_512_PLAINTEXT_SIZE, if the plaintext is shorter it must be +copied into a buffer of the proper length and zero padded up to its overall length. +\param[out] ciphertext points to the buffer that will receive the result of the encryption. +\return ::XLT_ERROR_SUCCESS on success, an \ref xlt_Errors "error code" on failure. +\note This function is present for test purpose, never use it in the application protected with XLight. +*/ +XND_LINK int XND_API xnd_xlt_never_use_this_rsa_encrypt(XND_DEVICE_CONTEXT dev_ctx, const unsigned char* public_key, unsigned int public_key_len, const unsigned char* plaintext, unsigned int plaintext_ciphertext_length, unsigned char* ciphertext); + +/** +\ingroup xnd_xlt_rsa +Performs a software RSA decryption. +\deprecated just use for test purpose + +See \ref xn_RSA_Protection for an introduction on the RSA protection in XLight. +\param[in] dev_ctx ::XND_DEVICE_CONTEXT handle referring to a real or fake device. +\param[in] private_key points to a buffer containing the formatted private RSA key to be used. +\param[in] private_key_len length of the formatted private key. The allowed values are ::XLT_RSA_1024_PRIV_KEY_SIZE and ::XLT_RSA_512_PRIV_KEY_SIZE. +\param[in] ciphertext points to the buffer containing the data to be decrypted. +\param[in] ciphertext_plaintext_length the length of the data to be decrypted, and the size of the receiving buffer. +The allowed values for this argument are ::XLT_RSA_1024_PLAINTEXT_SIZE and ::XLT_RSA_512_PLAINTEXT_SIZE, if the plaintext is shorter it must be +copied into a buffer of the proper length and zero padded up to its overall length. +\param[out] plaintext points to the buffer that will receive the result of the decryption. +\return ::XLT_ERROR_SUCCESS on success, an \ref xlt_Errors "error code" on failure. +*/ +XND_LINK int XND_API xnd_xlt_never_use_this_rsa_sw_decrypt(XND_DEVICE_CONTEXT dev_ctx, const unsigned char* private_key, unsigned int private_key_len, const unsigned char* ciphertext, unsigned int ciphertext_plaintext_length, unsigned char* plaintext); + +/** +\ingroup xnd_xlt_rsa +Runs an RSA decryption onto an XLight device. +See \ref xn_RSA_Protection for an introduction on the RSA protection in XLight. +\param[in] dev_ctx ::XND_DEVICE_CONTEXT handle referring to the selected device. +\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 xn_RSA_format). +\param[out] plaintext points to the buffer that will receive the result of the decryption. +\return ::XLT_ERROR_SUCCESS on success, an \ref xlt_Errors "error code" on failure. +\note The length of the ciphertext buffer must be the same of the plaintext. If the length is ::XLT_RSA_1024_PLAINTEXT_SIZE the 1024-bit key is used, +if the length is ::XLT_RSA_512_PLAINTEXT_SIZE the 512-bit key is used, for any other value an error is returned. +

      Supported version: this function is available on XLight devices version 2.0 or later. +*/ +XND_LINK int XND_API xnd_xlt_rsa_decrypt(XND_DEVICE_CONTEXT dev_ctx, const unsigned char* ciphertext, unsigned int ciphertext_plaintext_length, unsigned char* plaintext); + +/** +\ingroup xnd_xlt_bank +Perform a write operation in a locked bank (both normal and advanced Lock2 mode). + +See \ref xn_locked_memory. +\param[in] dev_ctx ::XND_DEVICE_CONTEXT handle referring to the selected device. +\param[in] bank the index of the memory bank that must be written. +\param[in] data points to a buffer of size ::XLT_LOCKED_TRANSFER_DATA containing the values computed by xnd_xlt_set_write_locked_serial_check() or +xlt_set_write_locked_group_check(). +\return returns ::XLT_ERROR_SUCCESS on success, an \ref xlt_Errors "error code" on failure. +\sa xnd_xlt_set_write_locked2_serial_check(), xnd_xlt_set_write_locked2_group_check(). +*/ +XND_LINK int XND_API xnd_xlt_write_locked(XND_DEVICE_CONTEXT dev_ctx, unsigned int bank, const unsigned char* data); + +/** +\ingroup xnd_xlt_bank +Perform a read operation in a locked bank (both normal and advanced Lock2 mode). + +See \ref xn_locked_memory. +\param[in] dev_ctx ::XND_DEVICE_CONTEXT handle referring to the selected device. +\param[in] bank the index of the memory bank that must be read. +\param[out] data points to a buffer of size ::XLT_LOCKED_TRANSFER_DATA that will receive the content of the memory bank in encrypted form. +\return returns ::XLT_ERROR_SUCCESS on success, an \ref xlt_Errors "error code" on failure. +\remark in order to get the data in plain form the function xnd_xlt_decrypt_locked2_data() must be used. +\note a locked bank can always be read using the xnd_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. + +A locked memory bank is subjected to a restriction in its dimension: only ::XLT_LOCKED_BANK_DATA_LENGTH will be freely available for reading and writing. +The remaining bytes are used by the locking mechanism management. +\sa xnd_xlt_decrypt_locked2_data(). +*/ +XND_LINK int XND_API xnd_xlt_read_locked(XND_DEVICE_CONTEXT dev_ctx, unsigned int bank, unsigned char* data); + +/** +\ingroup xnd_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 xnd_xlt_bank_lock2()). + +See \ref xn_locked_memory. +\param[in] dev_ctx ::XND_DEVICE_CONTEXT handle referring to a real or fake device. +\param[in] data points to a buffer of length ::XLT_LOCKED_BANK_DATA_LENGTH, that contains the value that must be written onto a locked bank. +\param[in] bank specify the index of the memory bank that must written. +\param[in] new_counter new counter value: this value must be greater than the counter value currently contained into the locked bank. +\param[in] serial the serial number of the XLight device target. +\param[in] dongle_key points to a buffer of length ::XLT_KEY_SIZE. It contains the AES-256 key Dongle Key set during xnd_xlt_getinfo() call. +\param[out] encryted_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 xnd_xlt_write_locked() function. +to the XLight device with the xnd_xlt_write() function in order to write data into a locked bank. +\return returns ::XLT_ERROR_SUCCESS on success, an \ref xlt_Errors "error code" on failure. + +\remark This function is to be considered as an utility not to be used diretly by the protected software. +It can be used by the vendor of the protected software in order to remotely update the locked memory of a device. +In this scenario the Dongle Key key must never be used onto the protected software, but used only to generate update for the device memory. +This way it is possible to remotely update the content of a locked bank. A locked bank can be read normally by a protected application using xnd_xlt_read(), so +this remote update technique can be used, for instance, for license management purposes. +\sa xnd_xlt_set_write_locked_group_check(), xnd_xlt_write_locked(), xnd_xlt_read_locked(), xnd_xlt_decrypt_locked_data(). +*/ +XND_LINK int XND_API xnd_xlt_set_write_locked_serial_check(XND_DEVICE_CONTEXT dev_ctx, const unsigned char* data, unsigned int bank, unsigned int new_counter, unsigned int serial, const unsigned char* dongle_key , unsigned char* encryted_data); + +/** +\ingroup xnd_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 xnd_xlt_bank_lock()). + +See \ref xn_locked_memory. +\param[in] dev_ctx ::XND_DEVICE_CONTEXT handle referring to a real or fake device. +\param[in] data points to a buffer of length ::XLT_LOCKED_BANK_DATA_LENGTH, that contains the value that must be written into the locked bank. +\param[in] bank specify the index of the memory bank that must written. +\param[in] new_counter new counter value: this value must be greater than the counter value currently contained into the locked bank. +\param[in] group_number the group number of the XLight devices for which the encrypted buffer is prepared. +\param[in] dongle_key points to a buffer of length ::XLT_KEY_SIZE. It contains the AES-256 key Dongle Key set during xnd_xlt_getinfo() call. +\param[out] encryted_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 xnd_xlt_write_locked() function. +\return returns ::XLT_ERROR_SUCCESS on success, an \ref xlt_Errors "error code" on failure. + +\remark The group number correspond to what is set on the dongle by xnd_xlt_bank_lock(). +It is intended to define subgroups of devices each of them must be treated in the same way. +For further notices see the comments of xnd_xlt_set_write_locked_serial_check(), they hold also for this function. +*/ +XND_LINK int XND_API xnd_xlt_set_write_locked_group_check(XND_DEVICE_CONTEXT dev_ctx, const unsigned char* data, unsigned int bank, unsigned int new_counter, unsigned int group_number, const unsigned char* dongle_key, unsigned char* encryted_data); + +/** +\ingroup xnd_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 xnd_xlt_bank_lock2()). + +See \ref xn_locked_memory. +\param[in] dev_ctx ::XND_DEVICE_CONTEXT handle referring to a real or fake device. +\param[in] data points to a buffer of length ::XLT_LOCKED_BANK_DATA_LENGTH, that contains the value that must be written onto a locked bank. +\param[in] bank specify the index of the memory bank that must written. +\param[in] new_counter new counter value: this value must be greater than the counter value currently contained into the locked bank. +\param[in] serial the serial number of the XLight device target. +\param[in] dongle_key points to a buffer of length ::XLT_KEY_SIZE. It contains the AES-256 key Dongle Key set during xnd_xlt_getinfo() call. +\param[out] encryted_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 xnd_xlt_write_locked() function. +to the XLight device with the xnd_xlt_write() function in order to write data into a locked bank. +\return returns ::XLT_ERROR_SUCCESS on success, an \ref xlt_Errors "error code" on failure. + +\remark This function is to be considered as an utility not to be used diretly by the protected software. +It can be used by the vendor of the protected software in order to remotely update the locked memory of a device. +In this scenario the Dongle Key key must never be used onto the protected software, but used only to generate update for the device memory. +This way it is possible to remotely update the content of a locked bank. A locked bank can be read normally by a protected application using xnd_xlt_read(), so +this remote update technique can be used, for instance, for license management purposes. +

      Supported version: this function is available on XLight devices version 1.01 or later. +\see xnd_xlt_set_write_locked2_group_check(), xnd_xlt_write_locked(), xnd_xlt_read_locked(), xnd_xlt_decrypt_locked2_data(). +*/ +XND_LINK int XND_API xnd_xlt_set_write_locked2_serial_check(XND_DEVICE_CONTEXT dev_ctx, const unsigned char* data, unsigned int bank, unsigned int new_counter, unsigned int serial, const unsigned char* dongle_key , unsigned char* encryted_data); + +/** +\ingroup xnd_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 xnd_xlt_bank_lock2()). + +See \ref xn_locked_memory. +\param[in] dev_ctx ::XND_DEVICE_CONTEXT handle referring to a real or fake device. +\param[in] data points to a buffer of length ::XLT_LOCKED_BANK_DATA_LENGTH, that contains the value that must be written into the locked bank. +\param[in] bank specify the index of the memory bank that must written. +\param[in] new_counter new counter value: this value must be greater than the counter value currently contained into the locked bank. +\param[in] group_number the group number of the XLight devices for which the encrypted buffer is prepared. +\param[in] dongle_key points to a buffer of length ::XLT_KEY_SIZE. It contains the AES-256 key Dongle Key set during xnd_xlt_getinfo() call. +\param[out] encryted_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 xnd_xlt_write_locked() function. +\return returns ::XLT_ERROR_SUCCESS on success, an \ref xlt_Errors "error code" on failure. + +\remark The group number correspond to what is set on the dongle by xnd_xlt_bank_lock2(). +It is intended to define subgroups of devices each of them must be treated in the same way. +For further notices see the comments of xnd_xlt_set_write_locked_serial_check(), they hold also for this function. +

      Supported version: this function is available on XLight devices version 1.01 or later. +*/ +XND_LINK int XND_API xnd_xlt_set_write_locked2_group_check(XND_DEVICE_CONTEXT dev_ctx, const unsigned char* data, unsigned int bank, unsigned int new_counter, unsigned int group_number, const unsigned char* dongle_key, unsigned char* encryted_data); + +/** +\ingroup xnd_xlt_bank +Retrieve the data in clear form of the content of a locked memory bank. + +See \ref xn_locked_memory. +\param[in] dev_ctx ::XND_DEVICE_CONTEXT handle referring to a real or fake device. +\param[in] encrypted_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 xnd_xlt_setup(). +\param[out] data points to a buffer of length ::XLT_BANK_SIZE that will receice the decrypted value. +\return returns ::XLT_ERROR_SUCCESS on success, an \ref xlt_Errors "error code" on failure. + +\remark xnd_xlt_decrypt_locked_data() retrieves the data in clear form of the content of a memory bank collected with a previous xnd_xlt_read_locked() call. +xnd_xlt_decrypt_locked_data() and xnd_xlt_read_locked() are used in a server client memory bank read operation. The xnd_xlt_read_locked() doesn't need of any password +and cryptographic key to be used but produces an encrypted buffer that can be understood only by the holder of the Dongle Key crypto-key. +xnd_xlt_read_locked() can be executed by non trusted people to collect information. Afterwards xnd_xlt_decrypt_locked_data() allows the authorized parts to decrypt +and read the content of the memory bank. + +The buffer returned by xnd_xlt_decrypt_locked_data() is ::XLT_KEY_SIZE bytes long, but only the first ::XLT_LOCKED_BANK_DATA_LENGTH bytes are the significant data +that can be written and used by the application. The remaining bytes are managed internally by the library and used for the 'locked bank' management. +These bytes convey information that may be retrieved using xnd_xlt_get_info_from_locked_bank(), such information are necessary for writing inside a locked bank. +\sa xnd_xlt_read_locked(), xnd_xlt_get_info_from_locked_bank() + +*/ +XND_LINK int XND_API xnd_xlt_decrypt_locked_data(XND_DEVICE_CONTEXT dev_ctx, const unsigned char* encrypted_data, const unsigned char* dongle_key, unsigned char* data); + +/** +\ingroup xnd_xlt_bank +Retrieve the data in clear form of the content of a locked with Lock2 memory bank. + +See \ref xn_locked_memory. +\param[in] dev_ctx ::XND_DEVICE_CONTEXT handle referring to a real or fake device. +\param[in] encrypted_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 xnd_xlt_setup(). +\param[out] data points to a buffer of length ::XLT_BANK_SIZE that will receice the decrypted value. +\return returns ::XLT_ERROR_SUCCESS on success, an \ref xlt_Errors "error code" on failure. + +\remark xnd_xlt_decrypt_locked2_data() retrieves the data in clear form of the content of a memory bank collected with a previous xnd_xlt_read_locked() call. +xnd_xlt_decrypt_locked2_data() and xnd_xlt_read_locked() are used in a server client memory bank read operation. The xnd_xlt_read_locked() doesn't need of any password +and cryptographic key to be used but produces an encrypted buffer that can be understood only by the holder of the Dongle Key crypto-key. +xnd_xlt_read_locked() can be executed by non trusted people to collect information. Afterwards xnd_xlt_decrypt_locked2_data() allows the authorized parts to decrypt +and read the content of the memory bank. + +The buffer returned by xnd_xlt_decrypt_locked2_data() is ::XLT_KEY_SIZE bytes long, but only the first ::XLT_LOCKED_BANK_DATA_LENGTH bytes are the significant data +that can be written and used by the application. The remaining bytes are managed internally by the library and used for the 'locked bank' management. +These bytes convey information that may be retrieved using xnd_xlt_get_info_from_locked_bank(), such information are necessary for writing inside a locked bank. +

      Supported version: this function is available on XLight devices version 1.01 or later. +\sa xnd_xlt_read_locked(), xnd_xlt_get_info_from_locked_bank() +*/ +XND_LINK int XND_API xnd_xlt_decrypt_locked2_data(XND_DEVICE_CONTEXT dev_ctx, const unsigned char* encrypted_data, const unsigned char* dongle_key, unsigned char* data); + +/** +\ingroup xnd_xlt_bank +Return information of a locked bank (both normal and advanced Lock2 mode). + +See \ref xn_locked_memory. +\param[in] dev_ctx ::XND_DEVICE_CONTEXT handle referring to a real or fake device. +\param[in] data points to a buffer of length ::XLT_BANK_SIZE, that contains the value retrieved from a locked bank by xnd_xlt_read() or xnd_xlt_decrypt_locked_data(). +\param[out] pbank points to an unsigned int that will contain the bank number to which the data belongs. This parameter is optional and may be set to NULL. +\param[out] pcounter points to an unsigned int that will contain the current counter field of the locked bank. This parameter is optional and may be set to NULL. +\param[out] pserial points to an unsigned int that will contain the serial number of the locked bank. This parameter is optional and may be set to NULL. +\param[out] pgroup_number points to an unsigned int that will contain the group number of the locked bank. This parameter is optional and may be set to NULL. +\return returns ::XLT_ERROR_SUCCESS on success, an \ref xlt_Errors "error code" on failure. +\remark If the data passed to this function comes from a non locked bank the outcome of this function is meaningless. +\remark The 'data' argument may come from a xnd_xlt_decrypt_locked_data() or a local xnd_xlt_read() call. +*/ +XND_LINK int XND_API xnd_xlt_get_info_from_locked_bank(XND_DEVICE_CONTEXT dev_ctx, const unsigned char* data, unsigned int* pbank, unsigned int* pcounter, unsigned int* pserial, unsigned int* pgroup_number); + +/** +\ingroup xnd_xlt_device +Virginize (reset) a demo XLight device. +\remark It doesn't work at all on a virtual XLight device of an xNodus device. +\param[in] dev_ctx ::XND_DEVICE_CONTEXT handle referring to the selected device. +\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 xnd_xlt_bank_freeze() and xnd_xlt_bank_lock2() functions which on normal devices cannot be reverted. + +\note OxySec supplies DEMO devices only for evaluation purpose and must be used only for testing on the standard devices. +*/ +XND_LINK int XND_API xnd_xlt_virg_demo(XND_DEVICE_CONTEXT dev_ctx); + +//\cond NOT_COMMENTED +XND_LINK int XND_API xnd_xlt_setserial(XND_DEVICE_CONTEXT dev_ctx, unsigned int sn); +//\endcond + +/** +\ingroup xnd_xlt_sd +Get memory size information of the memory flash in XLight SD devices. +\remark This function is not supported by xNodus devices. +\param[in] dev_ctx ::XND_DEVICE_CONTEXT handle referring to the selected device. +\param[out] p_mem_size_in_blocks points to an unsigned integer receiving the size in memory blocks (512 bytes) of the overall memory flash. +\param[out] p_enc_mem_size_in_blocks points to an unsigned integer receiving the size in memory blocks of the encrypted disk. If not present the return value is zero. +\return returns ::XLT_ERROR_SUCCESS on success, an \ref xlt_Errors "error code" on failure. +\see \ref xn_SDMEM. +*/ +XND_LINK int XND_API xnd_xlt_storage_get_mem_size(XND_DEVICE_CONTEXT dev_ctx, unsigned int *p_mem_size_in_blocks, unsigned int *p_enc_mem_size_in_blocks); + +/** +\ingroup xnd_xlt_sd +Initialize the memory flash of an XLight SD device. +\remark This function is not supported by xNodus devices. +\param[in] dev_ctx ::XND_DEVICE_CONTEXT handle referring to the selected device. +\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 xnd_xlt_setup() function. +\param[in] disk_password points to a buffer of length ::XLT_DISK_PASSWORD_SIZE containing the password that will be used to mount and unmount the encrypted disk. +\return returns ::XLT_ERROR_SUCCESS on success, an \ref xlt_Errors "error code" on failure. +\see \ref xn_SDMEM. +*/ +XND_LINK int XND_API xnd_xlt_storage_set(XND_DEVICE_CONTEXT dev_ctx, unsigned int locked_mem_size_in_blocks, const unsigned char* dongle_key, const unsigned char* disk_password); + +/** +\ingroup xnd_xlt_sd +Mount the encrypted disk of an XLight SD device. +\remark This function is not supported by xNodus devices. +\param[in] dev_ctx ::XND_DEVICE_CONTEXT handle referring to the selected device. +\param[in] disk_password points to a buffer of length ::XLT_DISK_PASSWORD_SIZE containing the password set by xnd_xlt_storage_set() function. +\return returns ::XLT_ERROR_SUCCESS on success, an \ref xlt_Errors "error code" on failure. +\see \ref xn_SDMEM. +*/ +XND_LINK int XND_API xnd_xlt_storage_unlock(XND_DEVICE_CONTEXT dev_ctx, const unsigned char* disk_password); + +/** +\ingroup xnd_xlt_sd +Mount the encrypted disk of an XLight SD device with read only access. +\remark This function is not supported by xNodus devices. +\param[in] dev_ctx ::XND_DEVICE_CONTEXT handle referring to the selected device. +\param[in] disk_password points to a buffer of length ::XLT_DISK_PASSWORD_SIZE containing the password set by xnd_xlt_storage_set() function. +\return returns ::XLT_ERROR_SUCCESS on success, an \ref xlt_Errors "error code" on failure. +\see \ref xn_SDMEM. +*/ +XND_LINK int XND_API xnd_xlt_storage_unlock_ro(XND_DEVICE_CONTEXT dev_ctx, const unsigned char* disk_password); + +/** +\ingroup xnd_xlt_sd +Unmount the encrypted disk of an XLight SD device. +\remark This function is not supported by xNodus devices. +\param[in] dev_ctx ::XND_DEVICE_CONTEXT handle referring to the selected device. +\param[in] disk_password points to a buffer of length ::XLT_DISK_PASSWORD_SIZE containing the password set by xnd_xlt_storage_set() function. +\return returns ::XLT_ERROR_SUCCESS on success, an \ref xlt_Errors "error code" on failure. +\see \ref xn_SDMEM. +*/ +XND_LINK int XND_API xnd_xlt_storage_lock(XND_DEVICE_CONTEXT dev_ctx, const unsigned char* disk_password); + +//\cond NOT_COMMENTED +XND_LINK int XND_API xnd_xlt_reserved(XND_DEVICE_CONTEXT dev_ctx, const unsigned char* direct_cmd, unsigned int direct_cmd_len, unsigned char* direct_resp, unsigned int direct_resp_size); +XND_LINK int XND_API xnd_xlt_reserved2(XND_DEVICE_CONTEXT dev_ctx, const unsigned char* dongle_key, unsigned int serial, const unsigned char* oxy_pre_cmd, unsigned int oxy_pre_cmd_len, unsigned char* direct_resp, unsigned int direct_resp_size); +XND_LINK int XND_API xnd_xlt_xlightsd_switch_to_nondemo(XND_DEVICE_CONTEXT dev_ctx); +XND_LINK int XND_API xnd_xlt_get_device_name(XND_DEVICE_CONTEXT dev_ctx, char* device_name, unsigned int device_name_size); +//\endcond + +/** +\ingroup xnd_xlt_counter +Update and get the value of a counter. +See \ref xn_TIMER_COUNTERS for an introduction to timer and counters management. +\param[in] dev_ctx ::XND_DEVICE_CONTEXT handle referring to the selected device. +\param[in] counter index of the counter to be used. This entry may take values from 0 to ::XLT_COUNTERS_NUM - 1. +\param[in] sub_value value to be subtracted to the indexed counter. If this value is 0 (zero) the counter value is read without modifying it. +\param[out] p_new_value point to an unsigned int value that will receive the value of the counter after the subtraction. +\return returns ::XLT_ERROR_SUCCESS on success, an \ref xlt_Errors "error code" on failure. + +If sub_value is greater than the current counter value, its new value will be zero and the function returns ::XLT_ERROR_SUCCESS. This is still the case also if the counter value is already zero. + +\see \ref xn_TIMER_COUNTERS. +*/ +XND_LINK int XND_API xnd_xlt_update_get_counter(XND_DEVICE_CONTEXT dev_ctx, unsigned int counter, unsigned int sub_value, unsigned int* p_new_value); + +/** +\ingroup xnd_xlt_timer +Retrieve the current value of the timer. +See \ref xn_TIMER_COUNTERS for an introduction to timer and counters management. +\param[in] dev_ctx ::XND_DEVICE_CONTEXT handle referring to the selected device. +\param[out] p_value point to an unsigned int value that will receive the current value of the timer. +\return returns ::XLT_ERROR_SUCCESS on success, an \ref xlt_Errors "error code" on failure. +\see \ref xn_TIMER_COUNTERS. +*/ +XND_LINK int XND_API xnd_xlt_get_timer(XND_DEVICE_CONTEXT dev_ctx, unsigned int* p_value); + +/** +\ingroup xnd_xlt_counter +Generate a command buffer to set a counter. +See \ref xn_TIMER_COUNTERS for an introduction to timer and counters management. +\param[in] dev_ctx ::XND_DEVICE_CONTEXT handle referring to a real or fake device. +\param[in] counter_cmd points to the structure ::XLT_COUNTER_CMD containing the settings to be applied to a counter. +\param[in] dongle_key points to the value of the Dongle Key set up by xnd_xlt_setup() function. +\param[out] enc_cmd points to a buffer that will receive the encrypted form of the command. +\param[in] enc_cmd_size length of the buffer pointed by enc_cmd. +\param[out] p_enc_cmd_len points to an unsigned integer that will contain the number of bytes copied in enc_cmd. This entry may be set also to 0 (NULL). +\return returns ::XLT_ERROR_SUCCESS on success, an \ref xlt_Errors "error code" on failure. +\see \ref xn_TIMER_COUNTERS. +*/ +XND_LINK int XND_API xnd_xlt_generate_counter_settings(XND_DEVICE_CONTEXT dev_ctx, 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 xnd_xlt_tc +Apply a timer or counter command onto the device. +See \ref xn_TIMER_COUNTERS for an introduction to timer and counters management. +\param[in] dev_ctx ::XND_DEVICE_CONTEXT handle referring to the selected device. +\param[in] enc_cmd point to a buffer containing the encrypted command to be applied to the device. +\param[in] enc_cmd_len the length of the encrypted command. +\return returns ::XLT_ERROR_SUCCESS on success, an \ref xlt_Errors "error code" on failure. +\see \ref xn_TIMER_COUNTERS. +*/ +XND_LINK int XND_API xnd_xlt_enc_apply_timer_counter(XND_DEVICE_CONTEXT dev_ctx, const unsigned char* enc_cmd, unsigned int enc_cmd_len); + +/** +\ingroup xnd_xlt_counter +Read in encrypted form the current state of all the counters of the device. +See \ref xn_TIMER_COUNTERS for an introduction to timer and counters management. +\param[in] dev_ctx ::XND_DEVICE_CONTEXT handle referring to the selected device. +\param[out] enc_data points to a buffer that will receive the encrypted counters data retrieved from the XLight dongle. +\param[in] enc_data_size length of the buffer pointed by enc_data. +\param[out] p_enc_data_len points to an unsigned integer that will receive the number of bytes copied in enc_data. This entry may be set also to 0 (NULL). +\return returns ::XLT_ERROR_SUCCESS on success, an \ref xlt_Errors "error code" on failure. +\see \ref xn_TIMER_COUNTERS. +*/ +XND_LINK int XND_API xnd_xlt_enc_read_counters(XND_DEVICE_CONTEXT dev_ctx, unsigned char* enc_data, unsigned int enc_data_size, unsigned int* p_enc_data_len); + +/** +\ingroup xnd_xlt_timer +Generate a command buffer to a set the timer. +See \ref xn_TIMER_COUNTERS for an introduction to timer and counters management. +\param[in] dev_ctx ::XND_DEVICE_CONTEXT handle referring to a real or fake device. +\param[in] timer_cmd points to the structure ::XLT_TIMER_CMD containing the settings to be applied to the timer. +\param[in] dongle_key points to the value of the Dongle Key set up by xnd_xlt_setup() function. +\param[out] enc_cmd points to a buffer that will receive the encrypted form of the command. +\param[in] enc_cmd_size length of the buffer pointed by enc_cmd. +\param[out] p_enc_cmd_len points to an unsigned integer that will contain the number of bytes copied in enc_cmd. This entry may be set also to 0 (NULL). +\return returns ::XLT_ERROR_SUCCESS on success, an \ref xlt_Errors "error code" on failure. +\see \ref xn_TIMER_COUNTERS. +*/ +XND_LINK int XND_API xnd_xlt_generate_timer_settings(XND_DEVICE_CONTEXT dev_ctx, 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 xnd_xlt_timer +Generate a command buffer to increase the timer value. +See \ref xn_TIMER_COUNTERS for an introduction to timer and counters management. +\param[in] dev_ctx ::XND_DEVICE_CONTEXT handle referring to a real or fake device. +\param[in] timer_add_cmd points to the structure ::XLT_TIMER_ADD_CMD containing the add timer settings to be applied. +\param[in] dongle_key points to the value of the Dongle Key set up by xnd_xlt_setup() function. +\param[out] enc_cmd points to a buffer that will receive the encrypted form of the command. +\param[in] enc_cmd_size length of the buffer pointed by enc_cmd. +\param[out] p_enc_cmd_len points to an unsigned integer that will contain the number of bytes copied in enc_cmd. This entry may be set also to 0 (NULL). +\return returns ::XLT_ERROR_SUCCESS on success, an \ref xlt_Errors "error code" on failure. +\see \ref xn_TIMER_COUNTERS. +*/ +XND_LINK int XND_API xnd_xlt_generate_timer_add_settings(XND_DEVICE_CONTEXT dev_ctx, 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 xnd_xlt_timer +Read in encrypted form the current state the device timer. +See \ref xn_TIMER_COUNTERS for an introduction to timer and counters management. +\param[in] dev_ctx ::XND_DEVICE_CONTEXT handle referring to the selected device. +\param[out] enc_data points to a buffer that will receive the encrypted timer data retrieved from the XLight dongle. +\param[in] enc_data_size length of the buffer pointed by enc_data. +\param[out] p_enc_data_len points to an unsigned integer that will receive the number of bytes copied in enc_data. This entry may be set also to 0 (NULL). +\return returns ::XLT_ERROR_SUCCESS on success, an \ref xlt_Errors "error code" on failure. +\see \ref xn_TIMER_COUNTERS. +*/ +XND_LINK int XND_API xnd_xlt_enc_read_timer(XND_DEVICE_CONTEXT dev_ctx, unsigned char* enc_data, unsigned int enc_data_size, unsigned int* p_enc_data_len); + +/** +\ingroup xnd_xlt_tc +Decrypt encrypted data from the device regarding timer or counters. +This function also extract data from encrypted commands. +See \ref xn_TIMER_COUNTERS for an introduction to timer and counters management. +\param[in] dev_ctx ::XND_DEVICE_CONTEXT handle referring to a real or fake device. +\param[in] enc_data points to encrypted data retrieved from the device or containing an encrypted command. +\param[in] enc_data_len length of the encrypted buffer. +\param[in] dongle_key points to the value of the Dongle Key set up by xnd_xlt_setup() function. +\param[out] retrieved_data points to an instance of structure ::XLT_TIMER_COUNTER_INFO that will contain the decryption of the data or command passed to this function. +\return returns ::XLT_ERROR_SUCCESS on success, an \ref xlt_Errors "error code" on failure. +\see \ref xn_TIMER_COUNTERS. +*/ +XND_LINK int XND_API xnd_xlt_timer_counters_retrieve(XND_DEVICE_CONTEXT dev_ctx, const unsigned char* enc_data, unsigned int enc_data_len, const unsigned char* dongle_key, XLT_TIMER_COUNTER_INFO* retrieved_data); + +/** +\ingroup xnd_xlt_date +Read in encrypted form the current state of the date license management of the device. +See \ref xn_DATE_LICENSING for an introduction to XLight license management based on the date. +\param[in] dev_ctx ::XND_DEVICE_CONTEXT handle referring to the selected device. +\param[out] enc_data points to a buffer that will receive the encrypted date license data retrieved from the XLight dongle. +\param[in] enc_data_size length of the buffer pointed by enc_data. +\param[out] p_enc_data_len points to an unsigned integer that will receive the number of bytes copied in enc_data. This entry may be set also to 0 (NULL). +\return returns ::XLT_ERROR_SUCCESS on success, an \ref xlt_Errors "error code" on failure. +See \ref xn_DATE_LICENSING +*/ +XND_LINK int XND_API xnd_xlt_enc_read_date(XND_DEVICE_CONTEXT dev_ctx, unsigned char* enc_data, unsigned int enc_data_size, unsigned int* p_enc_data_len); + +/** +\ingroup xnd_xlt_date +Read the current state of the date license management of the device. +See \ref xn_DATE_LICENSING for an introduction to XLight license management based on the date. +\param[in] dev_ctx ::XND_DEVICE_CONTEXT handle referring to the selected device. +\param[out] date_info points to a XLT_DATE_DATA struct that will receive the date license data of the connected device. +\return returns ::XLT_ERROR_SUCCESS on success, an \ref xlt_Errors "error code" on failure. +\note xnd_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: +

        +
      • functions_to_lock_mask, +
      • device_time, +
      • cmd_counter, +
      • max_missing_update_date_error, +
      • max_missing_update_signed_date_error and +
      • max_update_date_error. +
      +See \ref xn_DATE_LICENSING +*/ +XND_LINK int XND_API xnd_xlt_read_date(XND_DEVICE_CONTEXT dev_ctx, XLT_DATE_DATA* date_info); + +/** +\ingroup xnd_xlt_date +Set the current time (date) of the device. +See \ref xn_DATE_LICENSING for an introduction to XLight license management based on the date. +\param[in] dev_ctx ::XND_DEVICE_CONTEXT handle referring to the selected device. +\param[in] time the current Unix Time. +\return returns ::XLT_ERROR_SUCCESS on success, an \ref xlt_Errors "error code" on failure. +See \ref xn_DATE_LICENSING +*/ +XND_LINK int XND_API xnd_xlt_set_date(XND_DEVICE_CONTEXT dev_ctx, unsigned int time); + +/** +\ingroup xnd_xlt_date +Retrieve the challenge buffer generated by the XLight device for update signed update (\ref xn_SIGNED_DATE_UPDATE_CONSTRAINT) +The challenge buffer need to be used for setting the signed date onto the device +See \ref xn_DATE_LICENSING for an introduction to XLight license management based on the date. +\param[in] dev_ctx ::XND_DEVICE_CONTEXT handle referring to the selected device. +\param[out] enc_challenge points to a buffer that will receive an encoded form of the challenge buffer generated by the device. The length of the buffer must be not less than ::XLT_DATE_ENC_CHALLENGE_SIZE bytes long. +\param[in] enc_challenge_size length of the buffer pointed by challenge. +\param[out] p_enc_challenge_len points to an unsigned integer that will receive the length of the bytes copied in challenge. This entry may be set also to 0 (NULL). +\return returns ::XLT_ERROR_SUCCESS on success, an \ref xlt_Errors "error code" on failure. +See \ref xn_DATE_LICENSING +*/ +XND_LINK int XND_API xnd_xlt_date_get_challenge(XND_DEVICE_CONTEXT dev_ctx, unsigned char* enc_challenge, unsigned int enc_challenge_size, unsigned int* p_enc_challenge_len); + +/** +\ingroup xnd_xlt_date +Generate the license date expiration command +See \ref xn_DATE_LICENSING for an introduction to XLight license management based on the date (and the \ref xn_SetDateExpiration for an example of xnd_xlt_generate_date_expiration_cmd() usage). +\param[in] dev_ctx ::XND_DEVICE_CONTEXT handle referring to a real or fake device. +\param[in] cmd points to the structure containing all the settings for the license expiration command. +\param[in] dongle_key points to the value of the Dongle Key set up by xnd_xlt_setup() function. +\param[out] enc_cmd points to a buffer that will receive the encrypted form of the command for setting the expiration license date of an XLight device. The length of the buffer must be not less than ::XLT_DATE_ENC_EXP_CMD_SIZE bytes long. +\param[in] enc_cmd_size length of the buffer pointed by enc_cmd. +\param[out] p_enc_cmd_len points to an unsigned integer that will receive the length of the bytes copied in enc_cmd. This entry may be set also to 0 (NULL). +\return returns ::XLT_ERROR_SUCCESS on success, an \ref xlt_Errors "error code" on failure. +See \ref xn_DATE_LICENSING +*/ +XND_LINK int XND_API xnd_xlt_generate_date_expiration_cmd(XND_DEVICE_CONTEXT dev_ctx, const XLT_DATE_SET_EXPIRATION_CMD* cmd, const unsigned char* dongle_key, unsigned char* enc_cmd, unsigned int enc_cmd_size, unsigned int* p_enc_cmd_len); + +/** +\ingroup xnd_xlt_date +Generate the signed date command. +This command uses the challenge retrieved by the XLight device using the function xnd_xlt_date_get_challenge() and decoded by xnd_xlt_date_enc_retrieve(). +See \ref xn_DATE_LICENSING for an introduction to XLight license management based on the date. +\param[in] dev_ctx ::XND_DEVICE_CONTEXT handle referring to a real or fake device. +\param[in] time current Unix Time. +\param[in] challenge the challenge buffer generated by the dongle. +\param[in] challenge_len length of the challenge entry. +\param[in] dongle_key points to the value of the Dongle Key set up by xnd_xlt_setup() function. +\param[out] enc_cmd points to a buffer that will receive the encrypted form of the command for the signed update of the time of the device. The length of the buffer must be not less than ::XLT_DATE_SIG_UPD_CMD_SIZE bytes long. +\param[in] enc_cmd_size length of the buffer pointed by enc_cmd. +\param[out] p_enc_cmd_len points to an unsigned integer that will receive the length of the bytes copied in enc_cmd. This entry may be set also to 0 (NULL). +\return returns ::XLT_ERROR_SUCCESS on success, an \ref xlt_Errors "error code" on failure. +\note The challenge entry is not the enc_challenge argument returned by the function xnd_xlt_date_get_challenge(), but this is the challenge buffer of the structure ::XLT_DATE_CHALLENGE returned by xnd_xlt_date_enc_retrieve(). +See \ref xn_DATE_LICENSING +*/ +XND_LINK int XND_API xnd_xlt_generate_signed_date_cmd(XND_DEVICE_CONTEXT dev_ctx, unsigned int time, const unsigned char* challenge, unsigned int challenge_len, const unsigned char* dongle_key, unsigned char* enc_cmd, unsigned int enc_cmd_size, unsigned int* p_enc_cmd_len); + +/** +\ingroup xnd_xlt_date +Apply both license expiration setting and signed date update to the XLight device. +See \ref xn_DATE_LICENSING for an introduction to XLight license management based on the date. +\param[in] dev_ctx ::XND_DEVICE_CONTEXT handle referring to the selected device. +\param[in] enc_cmd point to a buffer containing the encrypted command to be applied to the device. +\param[in] enc_cmd_len the length of the encrypted command. +\return returns ::XLT_ERROR_SUCCESS on success, an \ref xlt_Errors "error code" on failure. +See \ref xn_DATE_LICENSING +*/ +XND_LINK int XND_API xnd_xlt_apply_date_enc_cmd(XND_DEVICE_CONTEXT dev_ctx, const unsigned char* enc_cmd, unsigned int enc_cmd_len); + +/** +\ingroup xnd_xlt_date +Decrypt the encrypted data returned by the device regarding the date license settings. +This function also extract data from encrypted commands for date management. +See \ref xn_DATE_LICENSING for an introduction to XLight license management based on the date. +\param[in] dev_ctx ::XND_DEVICE_CONTEXT handle referring to a real or fake device. +\param[in] enc_data points to encrypted data retrieved from the device or containing an encrypted command. +\param[in] enc_data_len length of the encrypted buffer. +\param[in] dongle_key points to the value of the Dongle Key set up by xnd_xlt_setup() function. +\param[out] retrieved_data points to an instance of structure ::XLT_DATE_INFO that will contain the decryption of the data or command passed to this function. +\return returns ::XLT_ERROR_SUCCESS on success, an \ref xlt_Errors "error code" on failure. +See \ref xn_DATE_LICENSING +*/ +XND_LINK int XND_API xnd_xlt_date_enc_retrieve(XND_DEVICE_CONTEXT dev_ctx, const unsigned char* enc_data, unsigned int enc_data_len, const unsigned char* dongle_key, XLT_DATE_INFO* retrieved_data); + +/** +\ingroup xnd_xlt_date +Date management function. +This function can take care of all the date management for the XLight device. +See \ref xn_DATE_LICENSING for an introduction to XLight license management based on the date (and expecially the paragraph \ref xn_AUTO_MANAGE_DATE_UPDATE). +An XLight device with date based licensing needs to be regularly accessed for setting its signed time and "normal" (non signed) time. +The non automatic functions used for such tasks are the xnd_xlt_apply_date_enc_cmd() (in conjunction with other vendor side operation) for the signed time and the xnd_xlt_set_date() for the non signed time. +xlt_date_manage() is able to completely substitute these tasks and regularly update the device also accessing internet services for getting signed update time. +\param[in] dev_ctx ::XND_DEVICE_CONTEXT handle referring to a real or fake device. +\param[in] cmd one of the \ref xlt_date_manage_cmd. +\param[in] device device index for the selection of a specific XLight device. This value runs from 0 to ::XLT_DEVICE_EXT_MAX -1. +\param[in] options the options of the command specified by the cmd argument. +\param[in] args points to a string containing arguments for addressing internet URL for signed time update or NTP time service. +\param[in] label points to a buffer with length of ::XLT_LABEL_SIZE byte containing the label of the XLight device to be addressed. If this entry is set to NULL, every device is addressed. +\return returns ::XLT_ERROR_SUCCESS on success, an \ref xlt_Errors "error code" on failure. + +\note The device argument is considered only when the cmd argument has values \ref ::XLT_DATE_MANAGE_DO_SET_TIME and ::XLT_DATE_MANAGE_DO_SET_TIME_ASYNC. + +The entry options and args gets values with different meaning depending on the value of the cmd entry: + +when cmd is chosen among +
        +
      • ::XLT_DATE_MANAGE_AUTO_START +
      • ::XLT_DATE_MANAGE_DO_SET_TIME +
      • ::XLT_DATE_MANAGE_DO_SET_TIME_ASYNC +
      + +The options entry takes the values shown here: \ref DATE_OPT_VAL; while args is a string containing web addresses to reach an NTP service or the OxySec signed date service: +see \ref xn_AUTO_MANAGE_DATE_UPDATE to see how to build it up. + +When cmd is ::XLT_DATE_MANAGE_SET_IDLE_TIME_SEC the options entry represents the second of tha new idle value (that is the time elapsing from one update test cicle and the other). Usually you don't need to +use this command value. The args entry is ignored. + +When cmd is ::XLT_DATE_MANAGE_MAKE_LOGS the options entry is considered as a boolean value: '1' starts the log management, '0' stops it (the default is no log, so you need to activate it to get the log). The args entry is ignored. + +When cmd is ::XLT_DATE_MANAGE_LOG_ONLY_ERROR the options entry is considered as a boolean value: '1' makes the log manager to keep track only of errors, '0' makes the log manager to keep track of every event (the defalut is '0'). The args entry is ignored. + +When cmd is ::XLT_DATE_MANAGE_LOG_SET_QUEUE_LEN the options entry is the value of the desired log buffer, that is the maximum number of the log records that can be taken. When that number is passed the older records are discarded. +The default value for this entry is 10000. The args entry is ignored. + +For every other value of the cmd entry options and args are ignored. +See \ref xn_DATE_LICENSING +*/ +XND_LINK int XND_API xnd_xlt_date_manage(XND_DEVICE_CONTEXT dev_ctx, unsigned int cmd, unsigned int device, unsigned int options, const char* args, const unsigned char* label); + +/** +\ingroup xnd_xlt_date +Retrieve the number of log records collected by the automatic date management process issued by xnd_xlt_date_manage(). +See \ref xn_DATE_LICENSING for an introduction to XLight license management based on the date. +\param[in] dev_ctx ::XND_DEVICE_CONTEXT handle referring to a real or fake device. +\param[out] p_num_entries points to an unsigned integer that will receive the number of log record currently collected. +\return returns ::XLT_ERROR_SUCCESS on success, an \ref xlt_Errors "error code" on failure. +See \ref xn_DATE_LICENSING +*/ +XND_LINK int XND_API xnd_xlt_date_manage_get_num_log_records(XND_DEVICE_CONTEXT dev_ctx, unsigned int* p_num_entries); + +/** +\ingroup xnd_xlt_date +Retrieve log records collected by the automatic date management process issued by xnd_xlt_date_manage(). +See \ref xn_DATE_LICENSING for an introduction to XLight license management based on the date. +\param[in] dev_ctx ::XND_DEVICE_CONTEXT handle referring to a real or fake device. +\param[in] starting_index the index of the first record to read from the log. +\param[in] num_entries the number of entries to read from the log. +\param[out] date_log the array of XLT_DATE_LOG structure that will receive the log records. The array must contain not less then num_entries items. +\param[out] p_num_entries_retrieved points to an unsigned integer that will receive the number of entries copied into the date_log array. This entry may be set also to 0 (NULL). +\return returns ::XLT_ERROR_SUCCESS on success, an \ref xlt_Errors "error code" on failure. +See \ref xn_DATE_LICENSING +*/ +XND_LINK int XND_API xnd_xlt_date_manage_get_log_records(XND_DEVICE_CONTEXT dev_ctx, unsigned int starting_index, unsigned int num_entries, XLT_DATE_LOG date_log[], unsigned int* p_num_entries_retrieved); + +/** +\ingroup xnd_xlt_ss +Open a session on the device (see \ref xnd_session_on_xlight). +\remark This function is not supported by xNodus devices, use xnd_xlt_session_open() instead. +\param[in] dev_ctx ::XND_DEVICE_CONTEXT handle referring to the selected device. +\param[in] password points to a buffer of length ::XLT_PASSWORD_SIZE. It contains the password to be assigned to the device. +\param[out] p_already_open points to an unsigned integer that will contain '1' if the session was already open, and '0' if not. If the pointer p_already_open is set to zero the argument is ignored. +\return returns ::XLT_ERROR_SUCCESS on success, an \ref xlt_Errors "error code" on failure. +\remark If the device referenced is xNodus the argument p_already_open is always ignored. +*/ +XND_LINK int XND_API xnd_xlt_c_open_session(XND_DEVICE_CONTEXT dev_ctx, const unsigned char* password, unsigned int* p_already_open); + +/** +\ingroup xnd_xlt_ss +Close a session on the device (see \ref xnd_session_on_xlight). +\remark This function is not supported by xNodus devices, use xnd_xlt_session_close() instead. +\param[in] dev_ctx ::XND_DEVICE_CONTEXT handle referring to the selected device. +\return returns ::XLT_ERROR_SUCCESS on success, an \ref xlt_Errors "error code" on failure. +*/ +XND_LINK int XND_API xnd_xlt_c_close_session(XND_DEVICE_CONTEXT dev_ctx); +//xnd_xlt_functions + + +//#define XND_XLT_MODULE_CONFIG_CMD_LEN 32 + +/** +\ingroup xnd_xlt_module +XLight command for setting the module mask inside an XLight device (see \ref xnd_modules). +\param[in] dev_ctx a generic device context handle. +\param[in] modules_mask a 64 bit variable that defines the modules that the protected application can open. +\param[in] dongle_key points to the dongle_key of the XLight device (see xnd_xlt_setup()). +\param[in] unix_time current time expressed in unix time. +\param[in] sn serial number of the target XLight device. If this entry is set to '0' every device will accept the command. +\param[out] enc_cmd points to a buffer that will receive the command for setting the module mask inside the specified XLight device using xnd_xlt_config_modules_apply(). +\param[in] enc_cmd_size the size in bytes of the buffer pointed by enc_cmd. +\param[out] p_enc_cmd_len points to an unsigned integer that will receive the actual length of the retrieved command written in enc_cmd. +\return returns ::XLT_ERROR_SUCCESS on success, an \ref xlt_Errors "error code" on failure. + +\remark The module support for XLight is based on a mask, because a module can be set (1) or inactive (0), there is no counting process to establish the number of instances of the pretected application that can gain access of the module, +here it is only possible to set 'all' or 'none'. The value 0x0000000000000001 set as usable the module 0, 0x0000000000000002 set as usable the module 1, ... 0x8000000000000000 set as usable the module 63. So to make active the modules +1,4, and 62 it must be used 0x4000000000000012. + +\remark This command works only on XLight version 2.50 and later +\see xnd_xlt_config_modules_apply() +*/ +XND_LINK int XND_API xnd_xlt_config_modules_cmd_wrap(XND_DEVICE_CONTEXT dev_ctx, XLT_ULONG_LONG modules_mask, const unsigned char* dongle_key, unsigned int unix_time, OPT unsigned int sn, unsigned char* enc_cmd, unsigned int enc_cmd_size, unsigned int* p_enc_cmd_len); + +/** +\ingroup xnd_xlt_module +Write the managed module mask on an XLight device applying the command generated by the function xnd_xlt_config_modules_cmd_wrap() (see \ref xnd_modules). +\param[in] dev_ctx a device context referring to the desired XLight device. +\param[in] enc_cmd points to a buffer containing the encrypted command generated by xnd_xlt_config_modules_cmd_wrap() +\param[in] enc_cmd_len the length in bytes of the encrypted command. +\return returns ::XLT_ERROR_SUCCESS on success, an \ref xlt_Errors "error code" on failure. +\remark This command works only on XLight version 2.50 and later. +\see xnd_xlt_config_modules_cmd_wrap() +*/ +XND_LINK int XND_API xnd_xlt_config_modules_apply(XND_DEVICE_CONTEXT dev_ctx, unsigned char* enc_cmd, unsigned int enc_cmd_len); + +//#define XLT_MODULE_SET_KEY_CMD_LEN 272 +/** +\ingroup xnd_xlt_module +XLight command for setting module challenge keys inside an XLight device (see \ref xnd_module_challenge). +\param[in] dev_ctx a generic device context handle. +\param[in] key_type key type of used key. This value takes values from \ref xnd_info_key_type. +\param[in] key points to a buffer containing a key expressed in XLight or xNodus format (see \ref xnd_key_data). +\param[in] key_len the length of the key entry. +\param[in] dongle_key points to the dongle_key of the XLight device (see xnd_xlt_setup()). +\param[in] sn serial number of the target XLight device. If this entry is set to '0' every device will accept the command. +\param[out] enc_cmd points to a buffer that will receive the command for setting the specific key inside the specified XLight device using xnd_xlt_set_modules_key_apply(). +\param[in] enc_cmd_size the size in bytes of the buffer pointed by enc_cmd. +\param[out] p_enc_cmd_len points to an unsigned integer that will receive the actual length of the retrieved command written in enc_cmd. +\return returns ::XLT_ERROR_SUCCESS on success, an \ref xlt_Errors "error code" on failure. +\parblock +\remark Only one key type (among RSA 512, RSA 1024 and AES) for the module challenge can be present on the XLight device at a time (while xNodus can select any of the present non volatile keys). +\endparblock +\parblock +\remark This command works only on XLight version 2.50 and later +\endparblock +*/ +XND_LINK int XND_API xnd_xlt_set_modules_key_cmd_wrap(XND_DEVICE_CONTEXT dev_ctx, unsigned int key_type, const unsigned char* key, unsigned int key_len, const unsigned char* dongle_key, OPT unsigned int sn, unsigned char* enc_cmd, unsigned int enc_cmd_size, unsigned int* p_enc_cmd_len); + +/** +\ingroup xnd_xlt_module +Write a module challenge key on an XLight device applying the command generated by the function xnd_xlt_set_modules_key_cmd_wrap() (see \ref xnd_module_challenge). +\param[in] dev_ctx a device context referring to the desired XLight device. +\param[in] enc_cmd points to a buffer containing the encrypted command generated by xnd_xlt_set_modules_key_cmd_wrap() +\param[in] enc_cmd_len the length in bytes of the encrypted command. +\return returns ::XLT_ERROR_SUCCESS on success, an \ref xlt_Errors "error code" on failure. + +\remark This command works only on XLight version 2.50 and later +*/ +XND_LINK int XND_API xnd_xlt_set_modules_key_apply(XND_DEVICE_CONTEXT dev_ctx, const unsigned char* enc_cmd, unsigned int enc_cmd_len); + + + +#ifdef __cplusplus +} +#endif + +#endif //XND_H_1239854890 diff --git a/OxySec/Lib/x32/oxyxlt.obj b/OxySec/Lib/x32/oxyxlt.obj deleted file mode 100644 index 3812dbf..0000000 Binary files a/OxySec/Lib/x32/oxyxlt.obj and /dev/null differ diff --git a/OxySec/Lib/x32/xnodus32.obj b/OxySec/Lib/x32/xnodus32.obj new file mode 100644 index 0000000..67765e4 Binary files /dev/null and b/OxySec/Lib/x32/xnodus32.obj differ diff --git a/OxySec/Lib/x64/oxyxlt.obj b/OxySec/Lib/x64/oxyxlt.obj deleted file mode 100644 index 79c070b..0000000 Binary files a/OxySec/Lib/x64/oxyxlt.obj and /dev/null differ diff --git a/OxySec/Lib/x64/xnodus.obj b/OxySec/Lib/x64/xnodus.obj new file mode 100644 index 0000000..edabee8 Binary files /dev/null and b/OxySec/Lib/x64/xnodus.obj differ