diff --git a/OxySec/Include/xlt.h b/OxySec/Include/xlt.h new file mode 100644 index 0000000..26d8367 --- /dev/null +++ b/OxySec/Include/xlt.h @@ -0,0 +1,1949 @@ +/** \file + * XLight Library. + * \mainpage XLight Library Documentation + +

+This is the documentation of the \ref xltapi "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. + +

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. + +

+

+\section adv_topics Advanced topics + +Read the following topics on Advanced XLight protection + + +

+*/ + + + + +#ifndef XLT_H_205672482 +#define XLT_H_205672482 + +#ifdef USE_BCC_502 +#define USE_BCC +#endif + +// We don't use "unsigned long long" because Borland C doesn't recognize it, while "unsigned __int64" works both in Borland and Microsoft Visual Studio +/** +an alias for unsigned __int64 +*/ +#define XLT_ULONG_LONG unsigned __int64 + +#ifdef __cplusplus +extern "C" { +#endif + +/** \name Compiler + * Linking and calling convention specifications for the current compiler. + */ +//@{ +#define XLT_LINK ///< Linking type of the exported XLight functions. +#define XLT_API __stdcall ///< Calling convention of the exported XLight functions. +//@} + +/** \defgroup constants Constants +Constants used by the \ref xltapi functions. +@{ +*/ + + +/** \defgroup Flags Flags + * Flag codes. + * Flags returned by the xlt_getinfo() function. They are returned as a mask of bits: for instance the returned value 0x110 means that the XLight device + * has XLT_FLAG_SETUP and XLT_FLAG_FROZEN_BANK0 set, that is the label is configured (already setup), and the memory bank 0 is frozen (i.e. it can't be rewritten). + //@{ + */ +#define XLT_FLAG_SETUP 0x10 ///< Set if the device has been initialized. +#define XLT_FLAG_FROZEN_BANK0 0x0100 ///< Set if the bank 0 is frozen (no longer writable) +#define XLT_FLAG_FROZEN_BANK1 0x0200 ///< Set if the bank 1 is frozen (no longer writable) +#define XLT_FLAG_FROZEN_BANK2 0x0400 ///< Set if the bank 2 is frozen (no longer writable) +#define XLT_FLAG_FROZEN_BANK3 0x0800 ///< Set if the bank 3 is frozen (no longer writable) +#define XLT_FLAG_FROZEN_BANK4 0x1000 ///< Set if the bank 4 is frozen (no longer writable) +#define XLT_FLAG_FROZEN_BANK5 0x2000 ///< Set if the bank 5 is frozen (no longer writable) +#define XLT_FLAG_FROZEN_BANK6 0x4000 ///< Set if the bank 6 is frozen (no longer writable) + +#define XLT_FLAG_LOCKED_BANK0 0x010000 ///< Set if the bank 0 is locked (writable only in encryption form) +#define XLT_FLAG_LOCKED_BANK1 0x020000 ///< Set if the bank 1 is locked (writable only in encryption form) +#define XLT_FLAG_LOCKED_BANK2 0x040000 ///< Set if the bank 2 is locked (writable only in encryption form) +#define XLT_FLAG_LOCKED_BANK3 0x080000 ///< Set if the bank 3 is locked (writable only in encryption form) +#define XLT_FLAG_LOCKED_BANK4 0x100000 ///< Set if the bank 4 is locked (writable only in encryption form) +#define XLT_FLAG_LOCKED_BANK5 0x200000 ///< Set if the bank 5 is locked (writable only in encryption form) +#define XLT_FLAG_LOCKED_BANK6 0x400000 ///< Set if the bank 6 is locked (writable only in encryption form) + +#define XLT_FLAG_TYPE_LOCK 0x800000 ///< Indicate the type of lock applied: if set to 1 the Lock2 is set + +//@} + +/** \defgroup Models Models + * 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 +//@} + +/** \defgroup Sizes Sizes + * Sizes in bytes of the buffers passed to and retrieved from the XLight APIs, plus other XLight consts. + @{ + */ +#define XLT_LABEL_SIZE 64 ///< Size of the Label field passed to the xlt_getinfo() and xlt_setup() functions. +#define XLT_PASSWORD_SIZE 32 ///< Size of the password field. +#define XLT_KEY_SIZE 32 ///< Size of a cryptographic Key. +#define XLT_BANK_SIZE 64 ///< Size of each bank of memory of the XLight device. +#define XLT_NUMBER_OF_BANKS 7 ///< Number of memory banks of the XLight device. +#define XLT_LOCKED_BANK_DATA_LENGTH 48 ///< Portion of the usable data for a locked bank. The rest of the bank is used for internal purpose. +#define XLT_LOCKED_TRANSFER_DATA 80 ///< data to be passed or retrieved using xlt_write_locked() and xlt_read_locked() +#define XLT_CIPHERTEXT_SIZE 16 ///< Size of the plaintext and ciphertext passed or retrieved by the crypto functions (xlt_encrypt(), xlt_decrypt() and xlt_challenge()) +#define XLT_DEVICE_MAX 16 ///< Max number of 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_RSA_512_BIT_SIZE 512 ///< length in bit of the public modulus of a 512 bit RSA key +#define XLT_RSA_512_WRAPPED_KEY_SIZE 144 ///< dimension of an RSA private key with modulus of 512 bit in its wrapped form +#define XLT_RSA_512_PUB_KEY_SIZE 68 ///< dimension of an RSA public key with modulus of 512 bit +#define XLT_RSA_512_PRIV_KEY_SIZE 132 ///< dimension of an RSA private key with modulus of 512 bit +#define XLT_RSA_512_PLAINTEXT_SIZE 64 ///< dimension of a plaintext for a 512 bit RSA key +#define XLT_RSA_512_CIPHERTEXT_SIZE XLT_RSA_512_PLAINTEXT_SIZE ///< dimension of a ciphertext for a 512 bit RSA key + +#define XLT_RSA_1024_BIT_SIZE 1024 ///< length in bit of the public modulus of a 1024 bit RSA key +#define XLT_RSA_1024_WRAPPED_KEY_SIZE 272 ///< dimension of an RSA private key with modulus of 1024 bit in its wrapped form +#define XLT_RSA_1024_PUB_KEY_SIZE 132 ///XLight SD trying to mount the non existent encrypted disk +#define XLT_ERROR_STOPPED -15 ///< The function was stopped by the timer, counter or date protection management +#define XLT_ERROR_TC_BAD_SERIAL -16 ///< Attempting to apply a time-counter setting on a device with unexpected serial number +#define XLT_ERROR_TC_BAD_FORMAT -17 ///< Bad timer-counter command or data format (for instance a wrong Dongle Key was used) +#define XLT_ERROR_TC_BAD_CMD_COUNTER -18 ///< The counter of the time-counter command was wrong (probably the command was already been applied) +#define XLT_ERROR_TC_BAD_VALUE -19 ///< Wrong timer or conter value, it's value exceed the allowed limit +#define XLT_ERROR_DATE_BAD_SERIAL -20 ///< Attempting to apply a date setting on a device with unexpected serial number +#define XLT_ERROR_DATE_BAD_FORMAT -21 ///< Bad date command or data format (for instance a wrong Dongle Key was used) +#define XLT_ERROR_DATE_BAD_CMD_COUNTER -22 ///< The counter of the date command was wrong (probably the command was already been applied) +#define XLT_ERROR_DATE_BAD_VALUE -23 ///< sent a date older than the one extimated by the device +#define XLT_ERROR_DATE_STOPPED -24 ///< The function was stopped by the date protection management +#define XLT_ERROR_DATE_NOT_CONFIGURED -25 ///< Date management not configured +#define XLT_ERROR_DATE_BAD_CHALLENGE -26 ///< Bad challenge value (value not expected) +#define XLT_ERROR_DATE_CHALLENGE_TIME_OUT -27 ///< The signed data was sent after challenge expiration +#define XLT_ERROR_DATE_UNUSED_SIGNED_TIME -28 ///< A signed date is not expected by the device +#define XLT_ERROR_RSA_INTERNAL_ERROR -29 ///< An internal error occurred running the RSA algorithm (it should never happen) + +/* __ * \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 +\see ::_XLT_TIMER_DATA +*/ +typedef struct _XLT_TIMER_DATA XLT_TIMER_DATA; + +/** \struct _XLT_TIMER_ADD_CMD +The structure contains the command for incrementing the timer. +*/ +struct _XLT_TIMER_ADD_CMD{ + unsigned int timer_value_minutes_to_add;///< minutes to add to the current value of the timer + unsigned int cmd_counter;///< strictly increasing value used to avoid command replication. If the data is retrieved this is the last value used for this field + unsigned int serial_number;///< the serial number of the referred XLight device +}; +/** \typedef XLT_TIMER_ADD_CMD +\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. +*/ +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) + 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 +\see ::_XLT_COUNTER_DATA +*/ +typedef struct _XLT_COUNTER_DATA XLT_COUNTER_DATA; + +/** \typedef XLT_TIMER_CMD +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. +*/ +typedef XLT_COUNTER_DATA XLT_COUNTER_CMD; + +/** \union _XLT_TC_INFO +Union of all timer and counters command and data, that is: +::XLT_TIMER_DATA, ::XLT_TIMER_ADD_CMD, ::XLT_COUNTER_DATA, ::XLT_TIMER_CMD and ::XLT_COUNTER_CMD. +*/ +union _XLT_TC_INFO{ + XLT_COUNTER_DATA counter_data[XLT_COUNTERS_NUM]; ///< array of XLT_COUNTER_DATA type containing information of all the counters. + XLT_TIMER_DATA timer_data; ///< XLT_TIMER_DATA type: counter information. + XLT_COUNTER_CMD counter_cmd; /// +
  • ::XLT_DATE_MANAGE_AUTO_START +
  • ::XLT_DATE_MANAGE_DO_SET_TIME +
  • ::XLT_DATE_MANAGE_DO_SET_TIME_ASYNC + +These values can be used together as bitmask. +@{ +*/ +#define XLT_DATE_OPT_USE_LOCAL_TIME 0x1 ///< the automatic date management thread (when needed) updates the date of the device using the time of the computer . +#define XLT_DATE_OPT_USE_INTERNET_TIME 0x2 ///< the automatic date management thread (when needed) updates the date of the device using internet time (NTP: Network Time Protocol). +#define XLT_DATE_OPT_USE_INTERNET_SIGNED_TIME 0x4 ///< the automatic date management thread (when needed) updates the signed date using the OxySec service. +#define XLT_DATE_OPT_IMMEDIATELY_USE_LOCAL_TIME 0x40 ///< the automatic date management thread immediately update the date of the device just after being started (also if not strictly necessary). +#define XLT_DATE_OPT_IMMEDIATELY_USE_INTERNET_TIME 0x80 ///< the automatic date management thread immediately update the date of the device just after being started using NTP (also if not strictly necessary). +#define XLT_DATE_OPT_IMMEDIATELY_USE_INTERNET_SIGNED_TIME 0x100 ///< the automatic date management thread immediately update the signed date of the device just after being started (also if not strictly necessary). +#define XLT_DATE_OPT_USE_INTERNET_TIME_FOR_SCHEDULING_TASKS 0x200 ///< this setting doesn't allow to use local time for library scheduling (the local time wont' be used at all). +//@} + + +//oxyservice = script.google.com/macros/s/AKfycbwKjS-n-Q3zuuu_37BjrUg7dnV1E2ZfBy0I5TsrnVLcZ5x8Rl4/exec +//ntp = pool.ntp.org +//oxyservice = script.google.com/macros/s/AKfycbwKjS-n-Q3zuuu_37BjrUg7dnV1E2ZfBy0I5TsrnVLcZ5x8Rl4/exec ; ntp = pool.ntp.org + +/** \defgroup LOG_INFO Log information +The function xlt_date_manage_get_log_records() returns log info related to the activity of the automatic thread management (\see xlt_date_manage()). +@{ +*/ +//Log actions values +/** \defgroup LOG_ACTION_VALS Log action values +The entry action of the structure ::XLT_DATE_LOG assumes the following values describing in which context +an event or an error occurred +*/ +#define LOG_ACTION_GET_DATE_INFO 1 ///< event or error while getting date info from the device +#define LOG_ACTION_SIGNED_TIME 2 ///< event or error while attempting to perform the signed date update procedure +#define LOG_ACTION_NTP_TIME 3 ///< event or error while getting the internet time +#define LOG_ACTION_LOCAL_TIME 4 ///< event or error while setting the date to the device using local time + +/** Log structure +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) + unsigned int device_index; ///< the index of the device on which the operation was done + unsigned int log_counter; ///< numeric value assigned to the log entry (every record of the log has a unique increasing value) +}XLT_DATE_LOG; +//@} + + +/** \defgroup releases_feature Release Features + * 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_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 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. + +//@} + +//@} //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. + + @{ +*/ + +/** + * 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[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. + \remark each device is associated to a unique device number and must be used by every function (except xlt_locate()) to address the device. + The user must not rely on this number to infer the order of insertion or the physical position of an XLight device in the USB HUB of the host computer. + * \par Example + * \code + #include "xlt.h" + #include + #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; + + for(device = 0; device < XLT_DEVICE_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("Version: %x.%02x\n", version >> 8, version & 0xFF); + if (model != XLT_MODEL_BASIC_USBHID) + printf("Unrecognized model!\n"); + if (flags & XLT_FLAG_SETUP){ + printf("The device is initialized\n"); + for(i = 0; i < XLT_NUMBER_OF_BANKS; i++){ + if (flags & (XLT_FLAG_FROZEN_BANK0 << i)) + printf("Bank %d frozen\n", i); + } + } + else + printf("The device is NOT initialized\n"); + + printf("The device Serial Number is: 0x%x\n", serial); + label_printable[XLT_LABEL_SIZE] = 0; + //N.B.: a label may contain not printable character + printf("Label: %s\n", (char*) label_printable); + } + } + ... + * \endcode + */ +XLT_LINK int XLT_API xlt_getinfo(unsigned int device, unsigned int* pversion, unsigned int* pmodel, unsigned int* pflags, unsigned int* pserial, unsigned char* label); + + +/** + 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] 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. + \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 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. + \par Example + \code + #include "xlt.h" + #include + + ... + + int status; + unsigned char label[XLT_LABEL_SIZE]; + unsigned char password[XLT_PASSWORD_SIZE]; + unsigned char dongle_key[XLT_KEY_SIZE]; + unsigned char challenge_response_key[XLT_KEY_SIZE]; + + ... + + //xlt_setup set label, password, user and challenge response keys (dongle_key and challenge_response_key) once for all. + //Only label must be specified, but it is strongly recommeded to set password, dongle_key, challenge_response_key as well + //with non trivial (random) values and keep them secret. + + //BEWARE: label, password, dongle_key and challenge_response_key are not strings but arrays, + //so fill them up to their entire size + + strcpy((char*)label, "My XLight label"); + memset(label + strlen("My XLight label"), 0x00, sizeof(label) - strlen("My XLight label")); + + ... + + status = xlt_setup(0, label, password, dongle_key, challenge_response_key); + if (status != XLT_ERROR_SUCCESS){ + printf("An error has occurred"); + } + * \endcode + */ +XLT_LINK int XLT_API xlt_setup(unsigned int device, const unsigned char* label, const unsigned char* password, const unsigned char* dongle_key, const unsigned char* cr_key); + + +/** + * 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. + \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. + \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 + \code + ... + int status; + unsigned int device = 0; + unsigned char password[XLT_PASSWORD_SIZE]; + unsigned char data[XLT_BANK_SIZE]; + + //BEWARE: data, is not a not string but an array, + //so fill it up to its entire size + strcpy((char*)data, "Some data"); + memset(data + strlen("Some data"), 0x00, sizeof(data) - strlen("Some data")); + + strcpy((char*)password, "My password"); + memset(password + strlen("My password"), 0x00, sizeof(password) - strlen("My password")); + + //write in bank 0 of an XLight dongle indexed by device = 0 + status = xlt_write(device, password, 0, data); + if (status != XLT_ERROR_SUCCESS){ + printf("An error has occurred\n"); + } + ... + \endcode +*/ +XLT_LINK int XLT_API xlt_write(unsigned int device, const unsigned char* password, unsigned int bank, const unsigned char* data); + + +/** +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. + \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. + \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 + \code + ... + int status; + unsigned int device = 0; + 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")); + + //read from bank 0 of an XLight dongle + status = xlt_read(device, password, 0, data); + if (status != XLT_ERROR_SUCCESS){ + printf("An error has occurred\n"); + } + else { + //N.B.: the data banks may contain not printable character + //(and in general it makes no sense print out memory content, this is just an example) + printf("Bank 0 data: %s\n", (char*)data); + } + ... + \endcode +*/ +XLT_LINK int XLT_API xlt_read(unsigned int device, const unsigned char* password, unsigned int bank, unsigned char* data); + + +/** +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] 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. + \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 + \code + ... + int status; + 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")); + + //freeze the bank 0 of a XLight dongle + //BEWARE: after the freeze the memory content of the bank 0 can't be modified any longer + status = xlt_bank_freeze(device, password, 0); + if (status != XLT_ERROR_SUCCESS){ + printf("An error has occurred\n"); + } + ... + \endcode + +*/ +XLT_LINK int XLT_API xlt_bank_freeze(unsigned int device, const unsigned char* password, unsigned int bank); + + +/** +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] 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. + \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. + + + \par Example + \code + ... + int status; + unsigned int device = 0; + unsigned char plaintext[XLT_CIPHERTEXT_SIZE]; + unsigned char ciphertext[XLT_CIPHERTEXT_SIZE]; + + //collect data to be encrypted + ... + status = xlt_encrypt(device, plaintext, ciphertext); + if (status == XLT_ERROR_SUCCESS){ + //ciphertext now contains the encryption of plaintext using AES 256 with key dongle_key passed to xlt_setup() + ... + } + ... + \endcode + + \par Another example just to show that xlt_decrypt() is the inverse of xlt_encrypt() + \code + ... + int status; + unsigned int device = 0; + unsigned char plaintext[XLT_CIPHERTEXT_SIZE]; + unsigned char ciphertext[XLT_CIPHERTEXT_SIZE]; + unsigned char retplaintext[XLT_CIPHERTEXT_SIZE]; + + //data to be encrypted (you can insert what you prefer) + plaintext[0] = 0x01; plaintext[1] = 0xa2; plaintext[2] = 0x62; plaintext[3] = 0x31; + plaintext[4] = 0x20; plaintext[5] = 0x36; plaintext[6] = 0x8b; plaintext[7] = 0x09; + plaintext[8] = 0x45; plaintext[9] = 0x31; plaintext[10] = 0x7c; plaintext[11] = 0x18; + plaintext[12] = 0x25; plaintext[13] = 0x81; plaintext[14] = 0x6b; plaintext[15] = 0xaa; + + status = xlt_encrypt(device, plaintext, ciphertext); + if (status != XLT_ERROR_SUCCESS){ + printf("Encryption failed!\n"); + } + else { + //ciphertext now contains the encryption of plaintext using AES 256 with key dongle_key passed to xlt_setup() + status = xlt_decrypt(device, ciphertext, retplaintext); + if (status == XLT_ERROR_SUCCESS && + memcmp(plaintext, retplaintext, XLT_CIPHERTEXT_SIZE) == 0){ + printf("OK: returned the original plaintext\n"); + } + else { + printf("Decryption failed!\n"); + } + } + ... + \endcode + + + */ +XLT_LINK int XLT_API xlt_encrypt(unsigned int device, const unsigned char* plaintext, unsigned char* ciphertext); + + +/** +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] 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. + \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(). + + \par Example + \code + ... + int status; + unsigned int device = 0; + unsigned char ciphertext[XLT_CIPHERTEXT_SIZE]; + unsigned char ret_plaintext[XLT_CIPHERTEXT_SIZE]; + + //collect data to be decrypted + ... + status = xlt_decrypt(device, ciphertext, ret_plaintext); + if (status == XLT_ERROR_SUCCESS){ + //ret_plaintext now contains the decryption of ciphertext using AES 256 with key dongle_key set passed to xlt_setup() + ... + } + ... + \endcode + + */ +XLT_LINK int XLT_API xlt_decrypt(unsigned int device, const unsigned char* ciphertext, unsigned char* plaintext); + + +/** +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] 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. + \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 + device. A good hacker debugging the code can come up to the encryption key, so the best policy is to make this task hard trying to hide + the key: for instance preparing the challenge and evaluating the response far from the code communicating with the dongle. The example below is not a good + example from this point of view and it must be considered just as an example. xlt_challenge() works in the same way of xlt_encrypt() but using a different AES key. + + \note Another possible and better way is to calculate many pairs challenge-presponse in a safe environment (i.e. not in the protected application) + and use such pairs to verify the response of the dongle. This method avoid the exposure of the Challenge Response Key. + + + \par Example + \code + ... + #include + #include "aes.h" + ... + int status; + unsigned int device = 0; + unsigned char challenge[XLT_CIPHERTEXT_SIZE]; + unsigned char response[XLT_CIPHERTEXT_SIZE]; + unsigned char expected_response[XLT_CIPHERTEXT_SIZE]; + unsigned char cr_key[XLT_KEY_SIZE]; + volatile unsigned char* c; + int i; + aes_ctx aes_ctx; + + + //compute the challenge (if possible always a new value) + srand(GetTickCount()); + for (i=0; i < XLT_CIPHERTEXT_SIZE; i++) + //it's better to use a cryptographic safe random generator (rand() is easy but not good) + challenge[i] = (unsigned char)rand(); + + + //challenge uses AES 256 encryption algorithm with key cr_key passed to xlt_setup() + status = xlt_challenge(device, challenge, response); + if (status != XLT_ERROR_SUCCESS){ + printf("Challenge Response failed!\n"); + //take the due action (halt execution) + } + else { + //check if the response is as expected (if not, the attached device is not what you expect to be!) + // we strongly recommend to perform the following check far and later from the xlt_challenge() call above, + //this makes the hacking job harder. + for(i = 0; i < XLT_KEY_SIZE; i++){ + cr_key[i]=(unsigned char)i*2; + } + //AES encryption key setup + aes_setkey(cr_key, XLT_KEY_SIZE, aes_enc, &aes_ctx); + c = cr_key; + for(i = 0; i < XLT_KEY_SIZE; i++){//cleanup + *c++ = 0; + } + + //AES encryption execution prototype: + //int aes_encrypt(const unsigned char* plaintext, unsigned char* ciphertext, const aes_ctx* ctx); + aes_encrypt(challenge, expected_response, &aes_ctx); + c = (unsigned char*) &aes_ctx; + for(i = 0; i < sizeof(aes_ctx); i++){//cleanup + *c++ = 0; + } + + if (memcmp(expected_response, response, XLT_CIPHERTEXT_SIZE) != 0){ + //the device has not computed what we expected + printf("Challenge Response failed!\n"); + //take the due action (halt execution) + } + } + ... + \endcode + */ +XLT_LINK int XLT_API xlt_challenge(unsigned int device, const unsigned char* challenge, unsigned char* response); + +/** +Load on a 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] 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. + + 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(). + 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 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. + \sa xlt_session_encrypt(), xlt_session_decrypt() and xlt_session_wrap_key(). + */ +XLT_LINK int XLT_API xlt_session_set_key(unsigned int device, unsigned int key_index, const unsigned char* wrapped_key); + +/** +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] 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. + + 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. + + See \ref 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. + \sa xlt_session_decrypt(), xlt_session_decrypt and xlt_session_wrap_key(). + */ +XLT_LINK int XLT_API xlt_session_encrypt(unsigned int device, unsigned int key_index, const unsigned char* plaintext, unsigned char* ciphertext); + +/** +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] 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. + + 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(). +

    Supported version: this function is available on XLight devices version 2.0 or later. + \sa xlt_session_wrap_key(). + */ +XLT_LINK int XLT_API xlt_session_decrypt(unsigned int device, unsigned int key_index, const unsigned char* ciphertext, unsigned char* plaintext); + +/** +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. + +\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 xlt_session_set_key(). +\note this function doesn't require any XLight device to be plugged in. + +See \ref Session_KeyPreliminary "here" for a source code example using this function. + +

    Supported version: this function is available on XLight devices version 2.0 or later. +\sa xlt_session_set_key(). +*/ +XLT_LINK int XLT_API xlt_session_wrap_key(const unsigned char* session_key, const unsigned char* dongle_key, unsigned char* wrapped_key); + +/** +Generate an RSA key. +See \ref RSA_Protection for an introduction on the RSA protection in XLight. +\param[in] bit_size the length in bit of the key to generate. The possible values are ::XLT_RSA_512_BIT_SIZE and ::XLT_RSA_1024_BIT_SIZE. +\param[out] private_key points to the buffer that will receive the generated RSA private key formatted with XLight RSA Key format (\ref RSA_format). +\param[in] private_key_size size of the private_key buffer. The size for a 1024 bit key is ::XLT_RSA_1024_PRIV_KEY_SIZE and the size for a 512 bit key is ::XLT_RSA_512_PRIV_KEY_SIZE. +\param[out] p_private_key_len points to an unsigned integer that will receive the actual length of the generated formatted private key. +\param[out] public_key points to the buffer that will receive the generated RSA public key formatted in XLight RSA Key format (\ref RSA_format). +If this parameter is NULL the public key is not retrieved. +\param[in] public_key_size size of the public_key buffer. The size for a 1024 bit key is ::XLT_RSA_1024_PUB_KEY_SIZE and the size for a 512 bit key is ::XLT_RSA_512_PUB_KEY_SIZE. +\param[out] p_public_key_len points to an unsigned integer that will receive the actual length of the generated formatted public key. +\return ::XLT_ERROR_SUCCESS on success, an \ref 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 xlt_rsa_wrap_privkey(). +*/ +XLT_LINK int XLT_API xlt_rsa_generate_key(unsigned int bit_size, unsigned char* private_key, unsigned int private_key_size, unsigned int* p_private_key_len, + unsigned char* public_key, unsigned int public_key_size, unsigned int* p_public_key_len); + +/** +Wraps an RSA key. +See \ref RSA_Protection for an introduction on the RSA protection in XLight. +\param[in] private_key points to a buffer containing a formatted private key +\param[in] private_key_length length of the RSA formatted key (\ref RSA_format). +\param[in] dongle_key points to a buffer containing 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. + +\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.0 or later. +\sa xlt_rsa_set_privkey() +*/ +XLT_LINK int XLT_API xlt_rsa_wrap_privkey(const unsigned char* private_key, unsigned int private_key_length, const unsigned char* dongle_key, unsigned char* wrapped_key, unsigned int wrapped_key_len); + +/** +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] 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. + +\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 +"modulus", not the length of the data containing the key (see \ref RSA_format). The device recognizes the two different key types and write them in their reserved memory place. + +The RSA key received from this function is not in clear form, but encrypted by the function xlt_rsa_wrap_privkey(). +In this way the RSA private key can be set by the protected program without exposing any relevant data, and hence preventing a hacker to understand the values (which would ruin all the security protocol based on RSA). + +\note an RSA key is present onto the device also after device removal because it is written in a non volatile memory, +nevertheless it can be always overwritten with a new one. +

    Supported version: this function is available on XLight devices version 2.0 or later. +*/ +XLT_LINK int XLT_API xlt_rsa_set_privkey(unsigned int device, const unsigned char* wrapped_key, unsigned int wrapped_key_length); + +/** +Performs RSA encryption. +\deprecated just use for test purpose + +See \ref RSA_Protection for an introduction on the RSA protection in XLight. +\param[in] public_key points to the buffer containing the formatted public key used for the encryption. +\param[in] public_key_len length of the formatted public key. The allowed values are ::XLT_RSA_1024_PUB_KEY_SIZE and ::XLT_RSA_512_PUB_KEY_SIZE. +\param[in] plaintext points to the buffer containing the data to be encrypted. +\param[in] plaintext_ciphertext_length the length of plaintext and the size of the buffer pointed by ciphertext. +The allowed values for this argument are ::XLT_RSA_1024_PLAINTEXT_SIZE and ::XLT_RSA_512_PLAINTEXT_SIZE, if the plaintext is shorter it must be +copied into a buffer of the proper length and zero padded up to its overall length. +\param[out] ciphertext points to the buffer that will receive the result of the encryption. +\return ::XLT_ERROR_SUCCESS on success, an \ref 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); + +/** +Performs a software RSA decryption. +\deprecated just use for test purpose + +See \ref RSA_Protection for an introduction on the RSA protection in XLight. +\param[in] private_key points to a buffer containing the formatted private RSA key to be used. +\param[in] private_key_len length of the formatted private key. The allowed values are ::XLT_RSA_1024_PRIV_KEY_SIZE and ::XLT_RSA_512_PRIV_KEY_SIZE. +\param[in] ciphertext points to the buffer containing the data to be decrypted. +\param[in] ciphertext_plaintext_length the length of the data to be decrypted, and the size of the receiving buffer. +The allowed values for this argument are ::XLT_RSA_1024_PLAINTEXT_SIZE and ::XLT_RSA_512_PLAINTEXT_SIZE, if the plaintext is shorter it must be +copied into a buffer of the proper length and zero padded up to its overall length. +\param[out] plaintext points to the buffer that will receive the result of the decryption. +\return ::XLT_ERROR_SUCCESS on success, an \ref 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); + +/** +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] 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. +\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. +*/ +XLT_LINK int XLT_API xlt_rsa_decrypt(unsigned int device, const unsigned char* ciphertext, unsigned int ciphertext_plaintext_length, unsigned char* plaintext); + +/** +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] 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. + +A locked memory bank can be written only using encrypted commands created by xlt_set_write_locked_group_check() or xlt_set_write_locked_serial_check() +and performed by xlt_write_locked(). +\note the group number is intended to define subgroups that must be treated in different ways. If there is no reason to create such differentiation +it must be inserted the same number for all devices, say 0. +The grouping allows to create a single encrypted command to modify the memory content of locked banks onto a large number of devices. + +\remark it is not useful to set a different group number for every device because it is already possible create a command for a single device by using its serial number. + +\note a locked bank can always be read using the xlt_read() function, but can't be written with xlt_write() any more. +A locked memory bank is subject to a restriction in its dimension: only ::XLT_LOCKED_BANK_DATA_LENGTH will be freely available for reading and writing. +The remaining bytes are used by the locking mechanism management. + +\sa xlt_bank_lock2(), xlt_set_write_locked_group_check(), xlt_set_write_locked_serial_check() +*/ +XLT_LINK int XLT_API xlt_bank_lock(unsigned int device, const unsigned char* password, unsigned int bank, unsigned int group_number); + +/** +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] 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. + +A locked2 memory bank can be written only using encrypted commands created by xlt_set_write_locked2_group_check() or xlt_set_write_locked2_serial_check() +and performed by xlt_write_locked(). +\note the group number is intended to define subgroups that must be treated in different ways. If there is no reason to create such differentiation +it must be inserted the same number for all devices, say 0. +The grouping allows to create a single encrypted command to modify the memory content of locked banks onto a large number of devices. + +\remark it is not useful to set a different group number for every device because it is already possible create a command for a single device by using its serial number. + +\note a locked bank can always be read using the xlt_read() function, but can't be written with xlt_write() any more. +A locked2 memory bank is subject to a restriction in its dimension: only ::XLT_LOCKED_BANK_DATA_LENGTH will be freely available for reading and writing. +The remaining bytes are used by the locking mechanism management. +

    Supported version: this function is available on XLight devices version 1.01 or later. +\sa xlt_set_write_locked2_group_check(), xlt_set_write_locked2_serial_check() +*/ +XLT_LINK int XLT_API xlt_bank_lock2(unsigned int device, const unsigned char* password, unsigned int bank, unsigned int group_number); + +/** +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] 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. +\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); + + +/** +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] 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. +\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. + +A locked memory bank is subjected to a restriction in its dimension: only ::XLT_LOCKED_BANK_DATA_LENGTH will be freely available for reading and writing. +The remaining bytes are used by the locking mechanism management. +\sa xlt_decrypt_locked2_data(). +*/ +XLT_LINK int XLT_API xlt_read_locked(unsigned int device, unsigned int bank, unsigned char* transfer_data); + + +/** +Encrypt the buffer to be written into a locked bank of a specific XLight device. +This data can be written only once and only in the device with a given serial number, provided that the destination bank is locked (see xlt_bank_lock2()). + +See \ref locked_memory. +\param[in] data points to a buffer of length ::XLT_LOCKED_BANK_DATA_LENGTH, that contains the value that must be written onto a locked bank. +\param[in] bank specify the index of the memory bank that must written. +\param[in] new_counter new counter value: this value must be greater than the counter value currently contained into the locked bank. +\param[in] serial the serial number of the XLight device target. +\param[in] dongle_key points to a buffer of length ::XLT_KEY_SIZE. It contains the AES-256 key 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. +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. + +\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 xlt_read(), so +this remote update technique can be used, for instance, for license management purposes. +\sa xlt_set_write_locked_group_check(), xlt_write_locked(), xlt_read_locked(), xlt_decrypt_locked_data(). +*/ +XLT_LINK int XLT_API xlt_set_write_locked_serial_check(const unsigned char* data, unsigned int bank, unsigned int new_counter, unsigned int serial, const unsigned char* dongle_key , unsigned char* transfer_data); + +/** +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()). + +See \ref locked_memory. +\param[in] data points to a buffer of length ::XLT_LOCKED_BANK_DATA_LENGTH, that contains the value that must be written onto a locked bank. +\param[in] bank specify the index of the memory bank that must written. +\param[in] new_counter new counter value: this value must be greater than the counter value currently contained into the locked bank. +\param[in] serial the serial number of the XLight device target. +\param[in] dongle_key points to a buffer of length ::XLT_KEY_SIZE. It contains the AES-256 key 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. +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. + +\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 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. +\sa xlt_set_write_locked2_group_check(), xlt_write_locked(), xlt_read_locked(), xlt_decrypt_locked2_data(). +*/ +XLT_LINK int XLT_API xlt_set_write_locked2_serial_check(const unsigned char* data, unsigned int bank, unsigned int new_counter, unsigned int serial, const unsigned char* dongle_key , unsigned char* transfer_data); + +/** +Encrypt the buffer to be written into a locked bank belonging to an XLight devices of a given group. +This data can be written only once provided that the destination bank is locked (see xlt_bank_lock()). + +See \ref locked_memory. +\param[in] data points to a buffer of length ::XLT_LOCKED_BANK_DATA_LENGTH, that contains the value that must be written into the locked bank. +\param[in] bank specify the index of the memory bank that must written. +\param[in] new_counter new counter value: this value must be greater than the counter value currently contained into the locked bank. +\param[in] group_number the group number of the XLight devices for which the encrypted buffer is prepared. +\param[in] dongle_key points to a buffer of length ::XLT_KEY_SIZE. It contains the AES-256 key 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. + +\remark the group number correspond to what is set on the dongle by xlt_bank_lock(). +It is intended to define subgroups of devices each of them must be treated in the same way. +For further notices see the comments of xlt_set_write_locked_serial_check(), they hold also for this function. +*/ +XLT_LINK int XLT_API xlt_set_write_locked_group_check(const unsigned char* data, unsigned int bank, unsigned int new_counter, unsigned int group_number, const unsigned char* dongle_key, unsigned char* transfer_data); + +/** +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()). + +See \ref locked_memory. +\param[in] data points to a buffer of length ::XLT_LOCKED_BANK_DATA_LENGTH, that contains the value that must be written into the locked bank. +\param[in] bank specify the index of the memory bank that must written. +\param[in] new_counter new counter value: this value must be greater than the counter value currently contained into the locked bank. +\param[in] group_number the group number of the XLight devices for which the encrypted buffer is prepared. +\param[in] dongle_key points to a buffer of length ::XLT_KEY_SIZE. It contains the AES-256 key 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. + +\remark the group number correspond to what is set on the dongle by xlt_bank_lock2(). +It is intended to define subgroups of devices each of them must be treated in the same way. +For further notices see the comments of xlt_set_write_locked_serial_check(), they hold also for this function. +

    Supported version: this function is available on XLight devices version 1.01 or later. +*/ +XLT_LINK int XLT_API xlt_set_write_locked2_group_check(const unsigned char* data, unsigned int bank, unsigned int new_counter, unsigned int group_number, const unsigned char* dongle_key, unsigned char* transfer_data); + +/** +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. + +\remark xlt_decrypt_locked_data() retrieves the data in clear form of the content of a memory bank collected with a previous xlt_read_locked() call. +xlt_decrypt_locked_data() and xlt_read_locked() are used in a server client memory bank read operation. The xlt_read_locked() doesn't need of any password +and cryptographic key to be used but produces an encrypted buffer that can be understood only by the holder of the Dongle Key crypto-key. +xlt_read_locked() can be executed by non trusted people to collect information. Afterwards xlt_decrypt_locked_data() allows the authorized parts to decrypt +and read the content of the memory bank. + +The buffer returned by xlt_decrypt_locked_data() is ::XLT_KEY_SIZE bytes long, but only the first ::XLT_LOCKED_BANK_DATA_LENGTH bytes are the significant data +that can be written and used by the application. The remaining bytes are managed internally by the library and used for the 'locked bank' management. +These bytes convey information that may be retrieved using xlt_get_info_from_locked_bank(), such information are necessary for writing inside a locked bank. +\sa xlt_read_locked(), xlt_get_info_from_locked_bank() +*/ +XLT_LINK int XLT_API xlt_decrypt_locked_data(const unsigned char* transfer_data, const unsigned char* dongle_key, unsigned char* data); + +/** +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. + +\remark xlt_decrypt_locked2_data() retrieves the data in clear form of the content of a memory bank collected with a previous xlt_read_locked() call. +xlt_decrypt_locked2_data() and xlt_read_locked() are used in a server client memory bank read operation. The xlt_read_locked() doesn't need of any password +and cryptographic key to be used but produces an encrypted buffer that can be understood only by the holder of the Dongle Key crypto-key. +xlt_read_locked() can be executed by non trusted people to collect information. Afterwards xlt_decrypt_locked2_data() allows the authorized parts to decrypt +and read the content of the memory bank. + +The buffer returned by xlt_decrypt_locked2_data() is ::XLT_KEY_SIZE bytes long, but only the first ::XLT_LOCKED_BANK_DATA_LENGTH bytes are the significant data +that can be written and used by the application. The remaining bytes are managed internally by the library and used for the 'locked bank' management. +These bytes convey information that may be retrieved using xlt_get_info_from_locked_bank(), such information are necessary for writing inside a locked bank. +

    Supported version: this function is available on XLight devices version 1.01 or later. +\sa xlt_read_locked(), xlt_get_info_from_locked_bank() +*/ +XLT_LINK int XLT_API xlt_decrypt_locked2_data(const unsigned char* transfer_data, const unsigned char* dongle_key, unsigned char* data); + +/** +Return information of a locked bank (both normal and advanced Lock2 mode). + +See \ref locked_memory. +\param[in] data points to a buffer of length ::XLT_BANK_SIZE, that contains the value retrieved from a locked bank by xlt_read() or xlt_decrypt_locked_data(). +\param[out] pbank points to an unsigned int that will contain the bank number to which the data belongs. This parameter is optional and may be set to NULL. +\param[out] pcounter points to an unsigned int that will contain the current counter field of the locked bank. This parameter is optional and may be set to NULL. +\param[out] pserial points to an unsigned int that will contain the serial number of the locked bank. This parameter is optional and may be set to NULL. +\param[out] pgroup_number points to an unsigned int that will contain the group number of the locked bank. This parameter is optional and may be set to NULL. +\return returns ::XLT_ERROR_SUCCESS on success, an \ref Errors "error code" on failure. +\remark if the data passed to this function comes from a non locked bank the outcome of this function is meaningless. +\remark the 'data' argument may come from a xlt_decrypt_locked_data() or a local xlt_read() call. +*/ +XLT_LINK int XLT_API xlt_get_info_from_locked_bank(const unsigned char* data, unsigned int* pbank, unsigned int* pcounter, unsigned int* pserial, unsigned int* pgroup_number); + + +/** +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. +\remark this function may be useful for testing allowing to completely cleanup a DEMO device, that is it doesn't work onto standard devices. +A demo device is distinguished by standard ones by its serial number: it is set to the value '1'. +This function may be useful especially while testing xlt_bank_freeze() and xlt_bank_lock2() functions which on normal devices cannot be reverted. + +\note OxySec supplies DEMO devices only for evaluation purpose and must be used only for testing on the standard devices. +*/ +XLT_LINK int XLT_API xlt_virg_demo(unsigned int device); + +/** +Cleanup the allocated memory by the XLight functions. +\remark in case of dll usage it is not necessary call this function, it is already called when the dll is unloaded. On the other hand it's not harmful to call it explicitly. +It is also possible call any other function after the xlt_close() is called, but in this case xlt_close() must be called again. +\note this function can't be called concurrently with any other function. + */ +XLT_LINK void XLT_API xlt_close(); + +/** +Initialize the environment for XLight management. +\return returns ::XLT_ERROR_SUCCESS on success, an \ref Errors "error code" on failure. + +\remark It is not necessary to call this function unless the running process is using multi-threading. In this case it is necessary call this +(or any other function accessing the device) function before starting using multi-threading. + +Every XLight function communicas with the device running xlt_init() if not already done, a problem may arises the first time the communication +environment is used if accessed simultaneously, so you must be sure that the first call is not done in concurrent access. +After the first call there is no problem in using multi-threading. +*/ +XLT_LINK int XLT_API xlt_init(); + +//XLT_LINK int XLT_API xlt_storage_get_mem_size(unsigned int device, unsigned int *p_mem_size_in_blocks); + +/** +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[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. +\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); + +/** +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] 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. +\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); + +/** +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] 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. +\see \ref SDMEM. +*/ +XLT_LINK int XLT_API xlt_storage_unlock(unsigned int device, const unsigned char* disk_password); + +/** +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] 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. +\see \ref SDMEM. +*/ +XLT_LINK int XLT_API xlt_storage_unlock_ro(unsigned int device, const unsigned char* disk_password); + +/** +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] 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. +\see \ref SDMEM. +*/ +XLT_LINK int XLT_API xlt_storage_lock(unsigned int device, const unsigned char* disk_password); + + + +/** +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] 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. + +If sub_value is greater than the current counter value, its new value will be zero and the function returns ::XLT_ERROR_SUCCESS. This is still the case also if the counter value is already zero. + +\see \ref TIMER_COUNTERS +*/ +XLT_LINK int XLT_API xlt_update_get_counter(unsigned int device, unsigned int counter, unsigned int sub_value, unsigned int* p_new_value); + +/** +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[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. +\see \ref TIMER_COUNTERS +*/ +XLT_LINK int XLT_API xlt_get_timer(unsigned int device, unsigned int* p_value); + +/** +Generate a command buffer to a set a counter. +See \ref TIMER_COUNTERS for an introduction to timer and counters management. +\param[in] counter_cmd points to the structure ::XLT_COUNTER_CMD containing the settings to be applied to a counter. +\param[in] dongle_key points to the value of the 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. +\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. +\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); + +/** +Generate a command buffer to a set the timer. +See \ref TIMER_COUNTERS for an introduction to timer and counters management. +\param[in] timer_cmd points to the structure ::XLT_TIMER_CMD containing the settings to be applied to the timer. +\param[in] dongle_key points to the value of the 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. +\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. +\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); + +/** +Generate a command buffer to increase the timer value. +See \ref TIMER_COUNTERS for an introduction to timer and counters management. +\param[in] timer_add_cmd points to the structure ::XLT_TIMER_ADD_CMD containing the add timer settings to be applied. +\param[in] dongle_key points to the value of the 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. +\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. +\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); + +/** +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] 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. +\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); + +/** +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[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. +\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); + +/** +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[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. +\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); + +/** +Decrypt encrypted data from the device regarding timer or counters. +This function also extract data from encrypted commands. +See \ref TIMER_COUNTERS for an introduction to timer and counters management. +\param[in] enc_data points to encrypted data retrieved from the device or containing an encrypted command. +\param[in] enc_data_len length of the encrypted buffer. +\param[in] dongle_key points to the value of the 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. +\see \ref TIMER_COUNTERS +*/ +XLT_LINK int XLT_API xlt_timer_counters_retrieve(const unsigned char* enc_data, unsigned int enc_data_len, const unsigned char* dongle_key, XLT_TIMER_COUNTER_INFO* retrieved_data); + +/////////////////////////////////////// +//DATE management + +/** +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[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. +*/ +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); + +/** +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[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. +\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: +

      +
    • functions_to_lock_mask, +
    • device_time, +
    • cmd_counter, +
    • max_missing_update_date_error, +
    • max_missing_update_signed_date_error and +
    • max_update_date_error. +
    +*/ +XLT_LINK int XLT_API xlt_read_date(unsigned int device, XLT_DATE_DATA* date_info); + +/** +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] time the current Unix Time. +\return returns ::XLT_ERROR_SUCCESS on success, an \ref Errors "error code" on failure. +*/ +XLT_LINK int XLT_API xlt_set_date(unsigned int device, unsigned int time); + +/** +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[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. +*/ +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); + + +/** +Generate the license date expiration command +See \ref DATE_LICENSING for an introduction to XLight license management based on the date (and the \ref SetDateExpiration for an example of xlt_generate_date_expiration_cmd() usage). +\param[in] cmd points to the structure containing all the settings for the license expiration command +\param[in] dongle_key points to the value of the 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[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. +*/ +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); + +/** +Generate the signed date command. +This command uses the challenge retrieved by the XLight device using the function xlt_date_get_challenge() and decoded by xlt_date_enc_retrieve(). +See \ref DATE_LICENSING for an introduction to XLight license management based on the date. +\param[in] time current Unix Time. +\param[in] challenge the challenge buffer generated by the dongle +\param[in] challenge_len length of the challenge entry +\param[in] dongle_key points to the value of the 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. +\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); + + +/** +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] 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. +*/ +XLT_LINK int XLT_API xlt_apply_date_enc_cmd(unsigned int device, const unsigned char* enc_cmd, unsigned int enc_cmd_len); + +/** +Decrypt the encrypted data returned by the device regarding the date license settings. +This function also extract data from encrypted commands for date management. +See \ref DATE_LICENSING for an introduction to XLight license management based on the date. +\param[in] enc_data points to encrypted data retrieved from the device or containing an encrypted command. +\param[in] enc_data_len length of the encrypted buffer. +\param[in] dongle_key points to the value of the 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. +*/ +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); + +/** +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. +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. + +\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 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. +*/ +XLT_LINK int XLT_API xlt_date_manage(unsigned int cmd, unsigned int device, unsigned int options, const char* args, const unsigned char* label); + +/** +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. +*/ +XLT_LINK int XLT_API xlt_date_manage_get_num_log_records(unsigned int* p_num_entries); + +/** +Retrieve log records collected by the automatic date management process issued by xlt_date_manage(). +See \ref DATE_LICENSING for an introduction to XLight license management based on the date. +\param[in] starting_index the index of the first record to read from the log +\param[in] num_entries the number of entries to read from the log +\param[out] date_log the array of XLT_DATE_LOG structure that will receive the log records. The array must contain not less then num_entries items +\param[out] p_num_entries_retrieved points to an unsigned integer that will receive the number of entries copied into the date_log array. This entry may be set also to 0 (NULL). +\return returns ::XLT_ERROR_SUCCESS on success, an \ref Errors "error code" on failure. +*/ +XLT_LINK int XLT_API xlt_date_manage_get_log_records(unsigned int starting_index, unsigned int num_entries, XLT_DATE_LOG date_log[], unsigned int* p_num_entries_retrieved); + + + +//\cond NOT_COMMENTED +XLT_LINK int XLT_API xlt_reserved(unsigned int device, const unsigned char* direct_cmd, unsigned int direct_cmd_len, + unsigned char* direct_resp, unsigned int direct_resp_size); +XLT_LINK int xlt_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 + + +#ifdef __cplusplus +} +#endif + +#endif diff --git a/OxySec/Lib/x32/oxyxlt.obj b/OxySec/Lib/x32/oxyxlt.obj new file mode 100644 index 0000000..3812dbf Binary files /dev/null and b/OxySec/Lib/x32/oxyxlt.obj differ diff --git a/OxySec/Lib/x64/oxyxlt.obj b/OxySec/Lib/x64/oxyxlt.obj new file mode 100644 index 0000000..79c070b Binary files /dev/null and b/OxySec/Lib/x64/oxyxlt.obj differ diff --git a/OxySec/XltDLLReference.chm b/OxySec/XltDLLReference.chm new file mode 100644 index 0000000..f1070c8 Binary files /dev/null and b/OxySec/XltDLLReference.chm differ