DarioS
4057 lines
271 KiB
C
4057 lines
271 KiB
C
// per in out (inout) usa \param[in,out]
|
|
|
|
/** \file
|
|
* xNodus Library.
|
|
* \mainpage xNodus-XLight Library Documentation
|
|
\anchor xnd_mainpage
|
|
|
|
// \note
|
|
> <span style="color:rgb(216,16,16); font-size:18px"><b>This is the reference manual for the xNodus and XLight APIs.<BR>
|
|
> Before reading this document it is strongly recommended to see the following documentation:</b></span>
|
|
> <ul>
|
|
> <li><a href="https://sites.google.com/a/oxysec.com/xnodus-tech-eng/home" target="_blank"><b><i>Online xNodus documentation</b></i></a>
|
|
> <li><a href="https://sites.google.com/a/oxysec.com/xlight-tech-eng/xlight" target="_blank"><b><i>Online XLight documentation</i></b></a>
|
|
> </ul>
|
|
> <i>To access these links it is necessary that <b>OxySec</b> has enabled a <b>Google account</b> of yours with due permissions. Ask <b>OxySec</b> what to do if you haven't such permission.</i>
|
|
|
|
<BR>
|
|
|
|
<P>
|
|
</b>This is the documentation of the \ref xnodus_api and \ref xltapi_old "APIs" for the communication between the host computer and the xNodus or XLight device.
|
|
|
|
<P>
|
|
The libraries are supplied in dll and obj format.
|
|
- Dlls: xnodus32.dll (32 bit) xnodus.dll (AMD 64 bit) are usable by any application which can be interfaced with DLLs.
|
|
- OBJs: xnodus.obj, (32 and 64 bit) can be integrated into "Microsoft Visual Studio 2008" C, C++ projects.
|
|
<P>
|
|
The interfaces supplied by the libraries (both dll and obj) are declered inside the file xnd.h and xlt.h and this documentation describes such interfaces.
|
|
|
|
<P>
|
|
The documentation is divided into the following sections:
|
|
- \subpage xnodus_doc
|
|
- \subpage xn_xlight_library
|
|
- \subpage xlt_library "The old XLight APIs documentation (use deprecated)"
|
|
*/
|
|
|
|
|
|
#ifndef XND_H_1239854890
|
|
#define XND_H_1239854890
|
|
|
|
#include "xlt.h"
|
|
|
|
#ifdef __cplusplus
|
|
extern "C" {
|
|
#endif
|
|
|
|
#ifndef OXY_LONG
|
|
#ifdef __LP64__ //MAC
|
|
#define OXY_LONG int
|
|
#else //__LP64__
|
|
#define OXY_LONG long
|
|
#endif //__LP64__
|
|
#endif //OXY_LONG
|
|
|
|
|
|
//\cond NOT_COMMENTED
|
|
#define XND_LINK XLT_LINK
|
|
#define XND_API XLT_API
|
|
|
|
#ifndef OPT
|
|
#define OPT
|
|
#endif
|
|
|
|
#ifndef OUT
|
|
#define OUT
|
|
#endif
|
|
|
|
#ifndef INOUT
|
|
#define INOUT
|
|
#endif
|
|
//\endcond
|
|
|
|
|
|
/** \defgroup xnodus_errors_misc xNodus miscellaneous errors
|
|
\ingroup xnodus_errors
|
|
Generic xNodus errors
|
|
@{
|
|
*/
|
|
#define XND_ERROR_SUCCESS XLT_ERROR_SUCCESS ///< the operation was successfully completed (alias for the ::XLT_ERROR_SUCCESS value)
|
|
#define XND_ERROR_NOT_FOUND XLT_ERROR_NOT_FOUND ///< Device not found.
|
|
#define XND_ERROR_INVALID_ARGUMENT XLT_ERROR_INVALID_ARGUMENT ///< Function called with an invalid argument.
|
|
#define XND_ERROR_INVALID_STATE XLT_ERROR_INVALID_STATE ///< Invalid state of the device for the required operation.
|
|
#define XND_ERROR_TRANSMIT XLT_ERROR_TRANSMIT ///< USB communication error.
|
|
#define XND_ERROR_RESOURCE XLT_ERROR_RESOURCE ///< Resource error (usually not enough memory).
|
|
|
|
|
|
#define XND_RELEASE_STILL_REFERENCED 1 ///< this is not a real error: returned by the release functions to indicate that the released object is still alive (used by other part of the program)
|
|
|
|
#define XND_ERROR_FIND_NO_MORE_DEVICES -2000 ///< returned by xnd_device_find_next(), it indicates that there is no more xNodus device to enumerate and that the search process can be terminated
|
|
#define XND_ERROR_FIND_NOT_FOUND_YET -2001 ///< returned by xnd_device_find_next(), it indicates that the search process is still running but at present no further xNodus devices are found
|
|
|
|
//@} //xnodus_errors_misc
|
|
|
|
/** \defgroup xnodus_errors_authentication xNodus Authentication errors
|
|
\ingroup xnodus_errors
|
|
Errors that may occurr during a session opening (xnd_xlt_session_open())
|
|
@{
|
|
*/
|
|
#define XND_ERROR_AU_AUTH_USER_NOT_FOUND -2040 ///< the User doesn't exist
|
|
#define XND_ERROR_AU_AUTH_PROTOCOL_ERROR -2041 ///< generic protocol error
|
|
#define XND_ERROR_AU_SESSION_TEMPORARY_UNAVAILABLE -2042 ///< retry to call the method in a while
|
|
#define XND_ERROR_AU_SESSION_NOT_FOUND -2043 ///< an expeceted session is not (or no longer) existing
|
|
#define XND_ERROR_AU_SESSION_SRV_ERROR -2044 ///< a session is already running
|
|
#define XND_ERROR_AU_SESSION_INVALID_KEY -2045 ///< the cryptographic key is not valid
|
|
#define XND_ERROR_AU_SESSION_ALREADY_RUNNING -2046 ///< a session is already running
|
|
#define XND_ERROR_AU_AUTH_XNODUS_SERIAL_NOT_FOUND -2047 ///< The AuthUser doesn't exist
|
|
#define XND_ERROR_AU_MISSING_KEY -2048 ///< a required cryptographic key is missing
|
|
//@} //xnodus_errors_authentication
|
|
|
|
/** \defgroup xnodus_errors_communication xNodus communication and network errors
|
|
\ingroup xnodus_errors
|
|
Communication error returned by the xNodus API library
|
|
@{
|
|
*/
|
|
#define XND_ERROR_NET_OPEN_LL_FAILURE -2200 ///< error opening the socket connection
|
|
#define XND_ERROR_NET_CONNECT_LL_FAILURE -2201 ///< socket connection failure
|
|
#define XND_ERROR_NET_CONNECT_LL_TIMEOUT -2202 ///< timeout while opening the socket connection
|
|
#define XND_ERROR_NET_SEND_FAILURE -2203 ///< transmission data to xNodus device failed
|
|
#define XND_ERROR_NET_RECV_FAILURE -2204 ///< receiving data from xNodus device failed
|
|
#define XND_ERROR_NET_RECV_BAD_FORMAT -2205 ///< bad format of the received data
|
|
#define XND_ERROR_CONNECTION_ABORTED -2206 ///< socket connection aborted by the API
|
|
#define XND_ERROR_NET_DNS_FAILURE -2210 ///< DNS resolution address failed
|
|
#define XND_ERROR_INVALID_SUBNET_MASK -2211 ///< wrong subnet mask (this error may occur searching for xNodus device)
|
|
#define XND_ERROR_UNKNOWN_TARGET -2212 ///< connecting to an unknown device
|
|
//@} //xnodus_errors_communication
|
|
|
|
/** \defgroup xnodus_errors_device xNodus errors returned by the device
|
|
\ingroup xnodus_errors
|
|
Errors returned directly by the xNodus device and passed back by the APIs
|
|
@{
|
|
*/
|
|
#define XND_DEV_BASE_ERR -3000 ///< offset value for the errors returned by the device
|
|
|
|
|
|
#define XND_ERROR_DEV_INVALID_ARGUMENT (XND_DEV_BASE_ERR -0x01) ///< invalid argument in a command #XND_DEV_BASE_ERR
|
|
#define XND_ERROR_DEV_INVALID_COMMAND (XND_DEV_BASE_ERR -0x02) ///< invalid command for the current status of the device
|
|
#define XND_ERROR_DEV_INVALID_COMMAND_SIGNATURE (XND_DEV_BASE_ERR -0x03) ///< corrupted command
|
|
#define XND_ERROR_DEV_INVALID_SEQUENCE_NUMBER (XND_DEV_BASE_ERR - 0x04) ///< command reused or synchronization lost between client and device
|
|
#define XND_ERROR_DEV_INVALID_DESTINATION (XND_DEV_BASE_ERR - 0x05) ///< an internal error (you shouldn't ever get)
|
|
#define XND_ERROR_DEV_INVALID_KEY_TYPE (XND_DEV_BASE_ERR - 0x06) ///< wrong or non supported type of the cryptographic key used
|
|
#define XND_ERROR_DEV_INVALID_DEVICE_STATUS (XND_DEV_BASE_ERR - 0x07) ///< status of the device invalid for the issued command
|
|
#define XND_ERROR_DEV_RESET_IN_PROGRESS (XND_DEV_BASE_ERR - 0x08) ///< the device cannot work because it is about to be reset (this happen only during device maintenance, configuration, or firmware update)
|
|
#define XND_ERROR_DEV_DEVICE_IS_EXPIRED (XND_DEV_BASE_ERR - 0x09) ///< the device license is expired
|
|
#define XND_ERROR_DEV_INVALID_COMMAND_COUNTER (XND_DEV_BASE_ERR - 0x0A) ///< invalid counter value for the remote command (the passed value is not greater than the xNodus internal value returned by xnd_get_info(), structure ::XND_INFO parameter 'remote_counter')
|
|
#define XND_ERROR_DEV_INVALID_SERIAL_NUMBER (XND_DEV_BASE_ERR - 0x0B) ///< the serial number doesn't match the expected one
|
|
#define XND_ERROR_DEV_INVALID_XLIGHT_INSTANCE (XND_DEV_BASE_ERR - 0x0C) ///< the referenced virtual XLight on xNodus doesn't exist
|
|
#define XND_ERROR_DEV_RSA_INTERNAL_ERROR (XND_DEV_BASE_ERR - 0x0D) ///< generic RSA internal error
|
|
#define XND_ERROR_DEV_RSA_KEY_ABSENT (XND_DEV_BASE_ERR - 0x0E) ///< the needed RSA key is not present in the device
|
|
#define XND_ERROR_DEV_RSA_INVALID_KEY_LEN (XND_DEV_BASE_ERR - 0x0F) ///< the cryptographic key length doesn't match the expected value
|
|
#define XND_ERROR_AES_INVALID_KEY_LEN (XND_DEV_BASE_ERR - 0x10) ///< the cryptographic key length doesn't match the expected value
|
|
#define XND_ERROR_AES_KEY_ABSENT (XND_DEV_BASE_ERR - 0x11) ///< the needed AES key is not present in the device
|
|
#define XND_ERROR_DEV_INTERNAL_ERROR (XND_DEV_BASE_ERR - 0xFF) ///< generic internal error (this should never occur)
|
|
|
|
|
|
#define XND_ERROR_DEV_USER_INVALID_TYPE (XND_DEV_BASE_ERR - 0x1003) ///< the user is not of the expected type for the function to be done
|
|
#define XND_ERROR_DEV_USER_INVALID_XLT_INDEX (XND_DEV_BASE_ERR - 0x1004) ///< a users refer to a non existing virtual XLight device
|
|
#define XND_ERROR_DEV_USER_NAME_ALREADY_EXIST (XND_DEV_BASE_ERR - 0x1005) ///< the user already exist (attempt to create an already existing user)
|
|
#define XND_ERROR_DEV_USER_NO_MORE_SESSIONS_AVAILABLE (XND_DEV_BASE_ERR - 0x1006) ///< the attempt to open a session failed because the limit of the licenses for the user is reached
|
|
#define XND_ERROR_DEV_USER_NO_SESSION_TO_CLOSE (XND_DEV_BASE_ERR - 0x1007) ///< no session of the user can be closed
|
|
#define XND_ERROR_DEV_USER_NO_MORE_MODULES_AVAILABLE (XND_DEV_BASE_ERR - 0x1008) ///< the attempt to access to a module failed because the limit of the licenses is reached
|
|
#define XND_ERROR_DEV_USER_EXPIRED (XND_DEV_BASE_ERR - 0x1009) ///< the session cannot be open because the user timelife is expired
|
|
#define XND_ERROR_DEV_USER_NOT_PRESENT (XND_DEV_BASE_ERR - 0x100A) ///< the attempt to open a session failed because the user is not recognized by xNodus
|
|
#define XND_ERROR_DEV_USER_NO_MORE_USER_AVAILABLE (XND_DEV_BASE_ERR - 0x100B) ///< it is impossible create a new user because the device already contains the maximum allowed number of user
|
|
#define XND_ERROR_DEV_USER_INVALID_NAME (XND_DEV_BASE_ERR - 0x100C) ///< an action of the user requests a change on a different user without permission
|
|
#define XND_ERROR_DEV_USER_ACCESS_DENIED (XND_DEV_BASE_ERR - 0x100E) ///< attempted to run a function not allowed to the current user
|
|
#define XND_ERROR_DEV_USER_OXY_LICENSES_EXPIRED (XND_DEV_BASE_ERR - 0x1010) ///< Oxysec license period for the usage of users is expired (a renewal is necessary)
|
|
|
|
#define XND_ERROR_DEV_SESSION_NO_MORE_SESSIONS_AVAILABLE (XND_DEV_BASE_ERR - 0x2001) ///< the attempt to open a session failed because the limit of the licenses is reached
|
|
#define XND_ERROR_DEV_SESSION_INVALID_SESSION_ID (XND_DEV_BASE_ERR - 0x2004) ///< the session of the issued command doesn't exist or it is expired
|
|
#define XND_ERROR_DEV_SESSION_INVALID_SESSION_STATUS (XND_DEV_BASE_ERR - 0x2005) ///< a command was sent when an authenticated session opening is not complete
|
|
#define XND_ERROR_DEV_SESSION_INVALID_CHALLENGE (XND_DEV_BASE_ERR - 0x2006) ///< the authentication process failed for an invalid challenge check
|
|
#define XND_ERROR_DEV_SESSION_INVALID_SIGNATURE (XND_DEV_BASE_ERR - 0x2007) ///< a client signature sent during authenticated session opening is wrong
|
|
#define XND_ERROR_DEV_SESSION_TIMEOUT_EXPIRED (XND_DEV_BASE_ERR - 0x2008) ///< the session timeout is expired (the session is no longer available)
|
|
#define XND_ERROR_DEV_SESSION_NOT_ENOUGH_LICENSES_AVAILABLE (XND_DEV_BASE_ERR - 0x2009) ///< OxySec license number reached (it is impossible assign the requested number of license because the available amount would be exceeded)
|
|
#define XND_ERROR_DEV_SESSION_NO_MORE_SESSION_AVAILABLE (XND_DEV_BASE_ERR - 0x2012) ///< No more session can be established because the phisical limit of the device has been found
|
|
|
|
#define XND_ERROR_DEV_SESSION_VK_INVALID_ALGO_TYPE (XND_DEV_BASE_ERR - 0x200A) ///< non existing algorithm id chosen for volatile key
|
|
#define XND_ERROR_DEV_SESSION_VK_INVALID_KEY_LEN (XND_DEV_BASE_ERR - 0x200C) ///< invalid key len of a volatile key
|
|
#define XND_ERROR_DEV_SESSION_VK_INVALID_DATA_LEN (XND_DEV_BASE_ERR - 0x200D) ///< invalid data length for encryption (it must be a multiple of 16)
|
|
#define XND_ERROR_DEV_SESSION_VK_INVALID_HEADER_SIZE (XND_DEV_BASE_ERR - 0x200E) ///< inviled header length for GCM encryption (it must be a multiple of 16)
|
|
#define XND_ERROR_DEV_SESSION_INVALID_CHECK_COUNTER (XND_DEV_BASE_ERR - 0x200F) ///< the counter is invalid in xnd_continue_session_check() call
|
|
#define XN_ERROR_SESSION_VK_INVALID_SIGNATURE (XND_DEV_BASE_ERR - 0x2019) ///< the GCM of a GCM decryption is not as expected (the data are corrupted)
|
|
|
|
#define XND_ERROR_DEV_MODULE_ALREADY_OPENED (XND_DEV_BASE_ERR - 0x3003) ///< the module is already open (and cannot be open again)
|
|
#define XND_ERROR_DEV_MODULE_INVALID_INDEX (XND_DEV_BASE_ERR - 0x3004) ///< non existing module referred
|
|
#define XND_ERROR_DEV_MODULE_NO_FREE_MODULE (XND_DEV_BASE_ERR - 0x3005) ///< no more license available for the module
|
|
#define XND_ERROR_DEV_MODULE_EXPIRED (XND_DEV_BASE_ERR - 0x3007) ///< the license time of the module is expired
|
|
|
|
#define XND_ERROR_DEV_LICENSE_MULTI_INSTANCE_INTERNAL_ERROR (XND_DEV_BASE_ERR - 0x2010) ///< an internal error occurred running a multi-instance session (see \ref xnd_users_group_lic)
|
|
#define XND_ERROR_DEV_LICENSE_MULTI_INSTANCE_NO_SESSION_TO_CLOSE (XND_DEV_BASE_ERR - 0x2011) ///< there is no actual session to close in a multi-instance session management (see \ref xnd_users_group_lic)
|
|
#define XND_ERROR_DEV_LICENSE_MULTI_INSTANCE_INVALID_CLIENT (XND_DEV_BASE_ERR - 0x2014) ///< the connected client is invalid
|
|
#define XND_ERROR_DEV_LICENSE_MULTI_INSTANCE_INVALID_RND (XND_DEV_BASE_ERR - 0x2015) ///< instance protocol error
|
|
#define XND_ERROR_DEV_LICENSE_MULTI_INSTANCE_NO_SESSION_AVAILABLE (XND_DEV_BASE_ERR - 0x2016) ///< Can't open a new instance, the computer has reached the maximum number of instances allowed
|
|
#define XND_ERROR_DEV_LICENSE_LICENSE_INVALID_INSTANCE_QUANTITY (XND_DEV_BASE_ERR - 0x2017) ///< the configured number of instance exceed the allowed limit (64 instances)
|
|
|
|
#define XND_ERROR_LICENSE_LOG_END (XND_DEV_BASE_ERR - 0x2018) ///< the log list is completed
|
|
|
|
//#define XND_ERROR_MODULE_INTERNAL_ERROR (XND_DEV_BASE_ERR - 0x30FF) // internal
|
|
|
|
//@} //xnodus_errors_device
|
|
|
|
|
|
|
|
/**
|
|
\defgroup xnd_RSA_const xNodus RSA size constant
|
|
\ingroup xnodus_defines
|
|
|
|
These are the constants for the various size of the RSA key managed by xNodus APIs that
|
|
extend the XLight definitions
|
|
|
|
@{
|
|
*/
|
|
#define XND_RSA_2048_BIT_SIZE 2048 ///< number of bits of the public modulus of a 2048 bit RSA key
|
|
#define XND_RSA_2048_PUB_KEY_SIZE 260 ///<length of an RSA public key with modulus of 2048 bit
|
|
#define XND_RSA_2048_PRIV_KEY_SIZE 516 ///< length of an RSA private key with modulus of 2048 bit
|
|
#define XND_RSA_2048_PLAINTEXT_SIZE 256 ///< length of a plaintext for a 2048 bit RSA key
|
|
#define XND_RSA_2048_CIPHERTEXT_SIZE XND_RSA_2048_PLAINTEXT_SIZE ///< length of a ciphertext for a 2048 bit RSA key
|
|
#define XND_RSA_2048_PRIV_KEY_PQE_SIZE 260 ///< length of an RSA private key with modulus of 2048 bit expressed in pqe form (see \ref xnd_users_key)
|
|
|
|
#define XND_RSA_4096_BIT_SIZE 4096 ///< number of bits of the public modulus of a 4096 bit RSA key
|
|
#define XND_RSA_4096_PUB_KEY_SIZE 516 ///<length of an RSA public key with modulus of 4096 bit
|
|
#define XND_RSA_4096_PRIV_KEY_SIZE 1028 ///< length of an RSA private key with modulus of 4096 bit
|
|
#define XND_RSA_4096_PLAINTEXT_SIZE 512 ///< length of a plaintext for a 4096 bit RSA key
|
|
#define XND_RSA_4096_CIPHERTEXT_SIZE XND_RSA_4096_PLAINTEXT_SIZE ///< length of a ciphertext for a 4096 bit RSA key
|
|
#define XND_RSA_4096_PRIV_KEY_PQE_SIZE 516 ///< length of an RSA private key with modulus of 4096 bit expressed in pqe form (see \ref xnd_users_key)
|
|
|
|
#define XND_RSA_512_BIT_SIZE XLT_RSA_512_BIT_SIZE ///< length in bit of the public modulus of a 512 bit RSA key
|
|
#define XND_RSA_512_WRAPPED_KEY_SIZE XLT_RSA_512_WRAPPED_KEY_SIZE ///< length of an RSA private key with modulus of 512 bit in its wrapped form
|
|
#define XND_RSA_512_PUB_KEY_SIZE XLT_RSA_512_PUB_KEY_SIZE ///< length of an RSA public key with modulus of 512 bit
|
|
#define XND_RSA_512_PRIV_KEY_SIZE XLT_RSA_512_PRIV_KEY_SIZE ///< length of an RSA private key with modulus of 512 bit
|
|
#define XND_RSA_512_PLAINTEXT_SIZE XLT_RSA_512_PLAINTEXT_SIZE ///< length of a plaintext for a 512 bit RSA key
|
|
#define XND_RSA_512_CIPHERTEXT_SIZE XLT_RSA_512_CIPHERTEXT_SIZE ///< length of a ciphertext for a 512 bit RSA key
|
|
#define XND_RSA_512_PRIV_KEY_PQE_SIZE 68 ///< length of an RSA private key with modulus of 512 bit expressed in pqe form (see \ref xnd_users_key)
|
|
|
|
#define XND_RSA_1024_BIT_SIZE XLT_RSA_1024_BIT_SIZE ///< length in bit of the public modulus of a 1024 bit RSA key
|
|
#define XND_RSA_1024_WRAPPED_KEY_SIZE XLT_RSA_1024_WRAPPED_KEY_SIZE ///< length of an RSA private key with modulus of 1024 bit in its wrapped form
|
|
#define XND_RSA_1024_PUB_KEY_SIZE XLT_RSA_1024_PUB_KEY_SIZE ///<length of an RSA public key with modulus of 1024 bit
|
|
#define XND_RSA_1024_PRIV_KEY_SIZE XLT_RSA_1024_PRIV_KEY_SIZE///< length of an RSA private key with modulus of 1024 bit
|
|
#define XND_RSA_1024_PLAINTEXT_SIZE XLT_RSA_1024_PLAINTEXT_SIZE ///< length of a plaintext for a 1024 bit RSA key
|
|
#define XND_RSA_1024_CIPHERTEXT_SIZE XLT_RSA_1024_CIPHERTEXT_SIZE ///< length of a ciphertext for a 1024 bit RSA key
|
|
#define XND_RSA_1024_PRIV_KEY_PQE_SIZE 132 ///< length of an RSA private key with modulus of 1024 bit expressed in pqe form (see \ref xnd_users_key)
|
|
|
|
//@} //xnd_RSA_const
|
|
|
|
struct _XND_XLT_ENV;
|
|
|
|
/**
|
|
\ingroup xnd_objects
|
|
xNodus-XLight environment
|
|
|
|
This is an handle that refers to the basic object that export the low level service for the xNodus and XLight API.
|
|
This object is required by many xNodus functions and must be initialized at the beginning and freed at the end of the protection calls.
|
|
Instances of this object are implicitly initialized using the original style XLight functions.
|
|
|
|
*/
|
|
typedef struct _XND_XLT_ENV *XND_XLT_ENV;
|
|
|
|
struct _XND_NET_DATA;
|
|
/**
|
|
\ingroup xnd_objects
|
|
xNodus Net Data
|
|
|
|
This is the handle that refers to the xNodus networking data object including address and timeout for the network operations.
|
|
|
|
This object hide the underlying communication protocol. At present IPv4 TCP and UDP are used, but IPv6 support may be provided in the future.
|
|
So to avoid the replication of many functions using new type of data it is introduced this object to hide the details but that will always
|
|
represents the network protocol plus additional datan xNodus uses during a network communication.
|
|
*/
|
|
typedef struct _XND_NET_DATA *XND_NET_DATA;
|
|
|
|
struct _XND_KEY_DATA;
|
|
/**
|
|
\ingroup xnd_objects
|
|
xNodus Key data
|
|
|
|
This is the handle to an object containing a generic cryptographic key. At present it can be a RSA private or public key and an AES key.
|
|
\see xnd_key_data
|
|
*/
|
|
typedef struct _XND_KEY_DATA *XND_KEY_DATA;
|
|
|
|
struct _XND_DEVICE_CONTEXT_DATA;
|
|
/**
|
|
\ingroup xnd_objects
|
|
xNodus device context data
|
|
|
|
This is the handle to the data collecting information to manage device contexts.
|
|
This handle can refers to multiple devices collecting data for different xNodus devices and XLight dongles.
|
|
A device context data defines the target devices the protected program can use.
|
|
\see \ref xnd_devctx_by_index.
|
|
*/
|
|
typedef struct _XND_DEVICE_CONTEXT_DATA *XND_DEVICE_CONTEXT_DATA;
|
|
|
|
struct _XND_DEVICE_CONTEXT;
|
|
/**
|
|
\ingroup xnd_objects
|
|
xNodus device context
|
|
|
|
This is the handle referring to a device context, that is an object collecting all the data required to communicate to a specific xNodus or XLight devices and implementing the communication protocol with it.
|
|
See \ref xnd_device_context.
|
|
|
|
Sometimes this object is instantiated not to refer to a real xNodus or XLight devices but just to allow the usage of API functions that don't communicate to
|
|
any device but use the object handle. For instance to prepare remote xNodus commands or generate an RSA key for XLight (xnd_remote_cmd_start_sbl(),xnd_xlt_rsa_generate_key()).
|
|
|
|
\see XND_DEVICE_CONTEXT_DATA
|
|
*/
|
|
typedef struct _XND_DEVICE_CONTEXT *XND_DEVICE_CONTEXT;
|
|
|
|
struct _XND_USER_FIND;
|
|
/**
|
|
\ingroup xnd_objects
|
|
xNodus user find context
|
|
|
|
This is the handle to the context for the xNodus users enumeration
|
|
|
|
*/
|
|
typedef struct _XND_USER_FIND *XND_USER_FIND;
|
|
|
|
|
|
struct _XND_USER_FIND_IDX;
|
|
/**
|
|
\ingroup xnd_objects
|
|
xNodus user find context (with index of the users)
|
|
|
|
This is the handle to the context for the xNodus users with index enumeration
|
|
|
|
*/
|
|
typedef struct _XND_USER_FIND_IDX *XND_USER_FIND_IDX;
|
|
|
|
|
|
struct _XND_DEVICE_FIND;
|
|
/**
|
|
\ingroup xnd_objects
|
|
xNodus device find context
|
|
|
|
This is the handle to the context of an xNodus device enumeration in a local area network
|
|
*/
|
|
typedef struct _XND_DEVICE_FIND *XND_DEVICE_FIND;
|
|
|
|
/**
|
|
IPv4 address structure
|
|
*/
|
|
typedef struct xnd_in_addr {
|
|
union {
|
|
struct { unsigned char s_b1,s_b2,s_b3,s_b4; } S_un_b;///< IPv4 address expressed as bytes
|
|
unsigned OXY_LONG S_addr;///< IPv4 address expressed as long in network byte order
|
|
} S_un; ///< union
|
|
} XND_IN_ADDR;
|
|
typedef XND_IN_ADDR *PXND_IN_ADDR; ///< pointer to ::XND_IN_ADDR structure
|
|
|
|
/**
|
|
Socket address (IPv4 address plus port)
|
|
*/
|
|
typedef struct xnd_sock_addr {
|
|
XND_IN_ADDR ipaddr; ///< xNodus address
|
|
unsigned short port; ///< port of the xNodus service
|
|
unsigned short _unused; ///< unused
|
|
}XND_SOCK_ADDR;
|
|
typedef XND_SOCK_ADDR *P_XND_SOCK_ADDR; ///< pointer to ::XND_SOCK_ADDR type
|
|
|
|
/**
|
|
Net configuration parameter of the xNodus device
|
|
|
|
The values of the structure contains the NET value to be applied to the xNodus device, or currently applied to xNodus if retieved by
|
|
the device (for instance with function command xnd_get_info()).
|
|
*/
|
|
typedef struct _XND_NET_PARAM{
|
|
unsigned int dhcp_active;///< if set to 1 the DHCP (Dynamic Host Configuration Protocol) is managed by the xNodus device, if set to 0 a static address sonfiguration is used
|
|
XND_IN_ADDR ip_address; ///< ip address of the xNodus device (if DHCP is off this is the fixed address of the device)
|
|
XND_IN_ADDR subnet_mask; ///< subnet mask of the xNodus device (if DHCP is off this is the fixed subnet mask of the device)
|
|
XND_IN_ADDR gateway; ///< gateway of the xNodus device (if DHCP is off this is the fixed gateway of the device)
|
|
XND_IN_ADDR dns1;///< primary DNS of the xNodus device (if DHCP is off this is the fixed primary DNS of the device)
|
|
XND_IN_ADDR dns2;///< secondary DNS of the xNodus device (if DHCP is off this is the fixed secondary DNS of the device)
|
|
unsigned short port;///< TCP/IP port used by xNodus for the communication (the default is 15678)
|
|
unsigned short _unused; ///< unused
|
|
}XND_NET_PARAM;
|
|
typedef XND_NET_PARAM *P_XND_NET_PARAM; ///< pointer to ::XND_NET_PARAM type
|
|
|
|
#define XND_DEFAULT_PORT 15678 ///< the default xNodus port value used by the TCP/IP communication. xNodus devices are shipped by OxySec with this value set, but it can be overriden by different network settings.
|
|
|
|
/**
|
|
\defgroup xnd_dev_status xNodus device status
|
|
\ingroup xnodus_defines
|
|
State of an xNodus device. Values that the entry 'device_status' of the structure ::XND_INFO can assume.
|
|
@{
|
|
*/
|
|
#define XND_DEV_DATA_XNODUS_DISABLED_DEVICE 0 ///< the device is disabled (it is impossible open any type of session and initialize it)
|
|
#define XND_DEV_DATA_XNODUS_OXY_LICENSE_IS_OK 1 ///< the device can be initialized
|
|
#define XND_DEV_DATA_XNODUS_IS_READY_TO_RUN 2 ///< the device is initialized, and users can be added or removed and the sessions can be established
|
|
#define XND_DEV_DATA_XNODUS_EXPIRED 3 ///< the OxySec license of the device is expired
|
|
//@} //xnd_dev_status
|
|
|
|
/**
|
|
\defgroup xnd_significant_flag Significant mask values
|
|
\ingroup xnodus_defines
|
|
|
|
Values for the mask of the significant values inside the structure of XND_INFO.
|
|
If a bit related to some entry is not set this means that that entry contains non significant values (usually set to zero),
|
|
while it is meaningful if the but is set.
|
|
@{
|
|
*/
|
|
#define XND_INFO_MASK_UC_ID 0x1 ///< 'sn' and 'architecture' entries in ::XND_INFO are significant
|
|
#define XND_INFO_MASK_FW_REL 0x2 ///< 'firmware_rel' entry in ::XND_INFO is significant
|
|
#define XND_INFO_MASK_DEV_STATUS 0x4 ///< 'device_status' entry in ::XND_INFO is significant
|
|
#define XND_INFO_MASK_LABEL 0x8 ///< 'label' entry in ::XND_INFO is significant
|
|
#define XND_INFO_MASK_FEATURES 0x10 ///< 'feature_mask' entry in ::XND_INFO is significant
|
|
#define XND_INFO_MASK_DEV_KEY 0x20 ///< 'xnodus_key_type', 'xnodus_key_len' and 'xnodus_key' entries in ::XND_INFO are significant
|
|
#define XND_INFO_MASK_ADMIN_KEY 0x40 ///< 'admin_key_type', 'admin_key_len' and 'admin_key' entries in ::XND_INFO are significant
|
|
#define XND_INFO_MASK_NET_SETTINGS 0x80 ///< 'net_param' entry in ::XND_INFO is significant
|
|
#define XND_INFO_MASK_OXY_USER_INFO 0x100 ///< 'oxy_max_num_licenses', 'oxy_max_num_users', 'oxy_users_license_expiration_time', 'oxy_dongle_license_expiration_time', 'assigned_licenses' entries in ::XND_INFO are significant
|
|
#define XND_INFO_MASK_CURRENT_USERS 0x200 ///< 'users_num' entry in ::XND_INFO is significant
|
|
#define XND_INFO_MASK_CURRENT_SESSIONS 0x400 ///< 'running_session_num' entry in ::XND_INFO is significant
|
|
#define XND_INFO_MASK_DEVICE_TIME 0x800 ///< 'xnodus_time' entry in ::XND_INFO is significant
|
|
//@} //xnd_significant_flag
|
|
|
|
#define XND_GET_INFO_MASK_MINIMUM (XND_INFO_MASK_UC_ID | XND_INFO_MASK_FW_REL | XND_INFO_MASK_DEV_STATUS | XND_INFO_MASK_LABEL | XND_INFO_MASK_OXY_USER_INFO) ///< the minimum mask usable for \ref xnd_significant_flag
|
|
|
|
|
|
//key type in info structures
|
|
/**
|
|
\defgroup xnd_info_key_type xNodus information key type
|
|
\ingroup xnodus_defines
|
|
|
|
These are the values to identify the cryptographic key type (for instance in the ::XND_INFO structure).
|
|
@{
|
|
*/
|
|
#define XND_KEY_TYPE_UNKNOWN 0xFFFFFFFF ///< unknown type
|
|
#define XND_KEY_TYPE_NO_KEY 0 ///< key is not present
|
|
#define XND_KEY_TYPE_AES 1 ///< AES 256 key
|
|
#define XND_KEY_TYPE_RSA_512_PUB 2 ///< RSA 512 public key
|
|
#define XND_KEY_TYPE_RSA_1024_PUB 3 ///< RSA 1024 public key
|
|
#define XND_KEY_TYPE_RSA_2048_PUB 4 ///< RSA 2048 public key
|
|
#define XND_KEY_TYPE_RSA_4096_PUB 5 ///< RSA 4096 public key
|
|
#define XND_KEY_TYPE_RSA_512_PRIV 6 ///< RSA 512 private key
|
|
#define XND_KEY_TYPE_RSA_1024_PRIV 7 ///< RSA 1024 private key
|
|
#define XND_KEY_TYPE_RSA_2048_PRIV 8 ///< RSA 2048 private key
|
|
#define XND_KEY_TYPE_RSA_4096_PRIV 9 ///< RSA 4096 private key
|
|
#define XND_KEY_TYPE_RSA_512_PRIV_EXT 10 ///< RSA 512 private key in extended form (that is the format used by the XLight RSA cryptographic functions)
|
|
#define XND_KEY_TYPE_RSA_1024_PRIV_EXT 11 ///< RSA 1024 private key in extended form (that is the format used by the XLight RSA cryptographic functions)
|
|
#define XND_KEY_TYPE_RSA_2048_PRIV_EXT 12 ///< RSA 2048 private key in extended form (that is the format used by the XLight RSA cryptographic functions)
|
|
#define XND_KEY_TYPE_RSA_4096_PRIV_EXT 13 ///< RSA 4096 private key in extended form (that is the format used by the XLight RSA cryptographic functions)
|
|
|
|
#define XND_KEY_TYPE_LEAVE_UNCHANGED XND_KEY_TYPE_NO_KEY ///< can be use in xnd_update_user() to left the key unchanged
|
|
|
|
//@} //xnd_info_key_type
|
|
|
|
/**
|
|
\ingroup xnodus_defines
|
|
length of the xNodus label, the counterpart of the label of XLight
|
|
*/
|
|
#define XNODUS_LABEL_SIZE XLT_LABEL_SIZE
|
|
/**
|
|
\ingroup xnodus_defines
|
|
maximum length of a cryptographic key
|
|
*/
|
|
#define XNODUS_MAX_KEY_SIZE (1024+4)
|
|
/**
|
|
Xnodus general information structure
|
|
*/
|
|
typedef struct _XND_INFO{
|
|
unsigned int set_values_mask;///<mask of the significant values of the structure (see \ref xnd_significant_flag)
|
|
unsigned char sn[16];///< Serial number
|
|
unsigned char architecture[8];///< architecture codes
|
|
unsigned int firmware_rel;///< firmware release
|
|
unsigned int device_status; ///< status of the device (see \ref xnd_dev_status)
|
|
unsigned char label[XNODUS_LABEL_SIZE]; ///< the label of the device (a sort of name of xNodus)
|
|
unsigned int feature_mask; ///< currently set to zero
|
|
unsigned int xnodus_key_type; ///< type of the xNodus cryprographic key (values from \ref xnd_info_key_type)
|
|
unsigned int xnodus_key_len; ///< length of the xNodus cryprographic key
|
|
unsigned char xnodus_key[XNODUS_MAX_KEY_SIZE];///< xNodus cryprographic key value
|
|
unsigned int admin_key_type; ///< type of the administrator user cryprographic key (values from \ref xnd_info_key_type)
|
|
unsigned int admin_key_len; ///< length of administrator user cryprographic key
|
|
unsigned char admin_key[XNODUS_MAX_KEY_SIZE];///< administrator user cryprographic key value
|
|
XND_NET_PARAM net_param; ///< network parameters (see XND_NET_PARAM)
|
|
unsigned int oxy_max_num_licenses;///< maximum number of licenses available on the xNodus device set by OxySec
|
|
unsigned int oxy_dongle_license_expiration_time;///< license expiration date of the xNodus device expressed in unix time (value set by OxySec)
|
|
unsigned int oxy_max_num_users; ///< maximum number of users that can be inserted into the xNodus device (value set by OxySec). The 'Anonymous' user is not counted
|
|
unsigned int oxy_users_license_expiration_time; ///< license expiration date of the users present on the device expressed in unix time (value set by OxySec)
|
|
unsigned int assigned_licenses; ///< amount of licenses assigned to the users
|
|
unsigned int users_num; ///< current number of users present in the xNodus device
|
|
unsigned int running_session_num; ///< number of currently running sessions on the xNodus device
|
|
unsigned int xnodus_time; ///< date of the XNodus device expressed in unix time
|
|
unsigned int remote_counter; ///< counter for remote operations
|
|
unsigned int orc; ///< reserved
|
|
}XND_INFO;
|
|
typedef XND_INFO *P_XND_INFO; ///< pointer to ::XND_INFO type
|
|
|
|
/**
|
|
\defgroup xnd_user_types xNodus user types
|
|
\ingroup xnodus_defines
|
|
|
|
See \ref xnd_users_types for an introduction to user types.
|
|
@{
|
|
*/
|
|
#ifndef XND_USER_TYPE_ANONYMOUS
|
|
#define XND_USER_TYPE_ANONYMOUS 1 ///< 'Anonymous' user
|
|
#define XND_USER_TYPE_USER 2 ///< user with a name (user with identity)
|
|
#define XND_USER_TYPE_ADMIN 3 ///< 'administrator' user
|
|
#endif
|
|
//@} //xnd_user_types
|
|
|
|
#define XND_USER_NAME_LEN 32 ///< the length of the name of the user with identity (::XND_USER_TYPE_USER)
|
|
/**
|
|
Users name data structure
|
|
|
|
A user name in xNodus is defined by its type and 32 bytes (in general a string is aused)
|
|
*/
|
|
typedef struct _XND_USER_NAME{
|
|
unsigned int user_type; ///< the type is part of the name, it may take values from \ref xnd_user_types
|
|
unsigned char user_name[XND_USER_NAME_LEN]; ///< the user name (considered only for ::XND_USER_TYPE_USER users)
|
|
}XND_USER_NAME;
|
|
typedef XND_USER_NAME *P_XND_USER_NAME; ///< pointer to ::XND_USER_NAME type
|
|
|
|
|
|
#define XND_MAX_NUM_MODULES 64 ///< maximum number of modules
|
|
#define XND_MAX_VIRTUAL_XLIGHT_NUM 32 ///< maximum number of virtual XLight on xNodus
|
|
|
|
/**
|
|
\defgroup xnd_permision_mask Permission mask values
|
|
\ingroup xnodus_defines
|
|
|
|
The bitwise 'OR' operation of a subset of the following values defines the operations (functions) an user is allowed to run.
|
|
This value is set inside the entry 'permission_mask' of the structure ::XND_USER_INFO.
|
|
@{
|
|
*/
|
|
#define XND_PMASK_SS_GET_INFO ((XLT_ULONG_LONG)1 << 0) ///< collect device information of the xNodus device (xnd_get_info())
|
|
//\cond NOT_COMMENTED
|
|
#define XND_PMASK_SS_SET_LICENSES ((XLT_ULONG_LONG)1 << 1)
|
|
//\endcond
|
|
#define XND_PMASK_SS_INIT_DEVICE ((XLT_ULONG_LONG)1 << 2) ///< initialize the xNodus device (xnd_init_device())
|
|
#define XND_PMASK_SS_VIRGINIZE ((XLT_ULONG_LONG)1 << 3) ///< virginize xNodus: restore it to the intial state of the memory with default keys and no users except the 'Anonymous' (xnd_virginize())
|
|
#define XND_PMASK_SS_SET_NETWORK ((XLT_ULONG_LONG)1 << 4) ///< set network configuration data (xnd_set_network_param())
|
|
#define XND_PMASK_SS_SET_VISIBLE_INFO ((XLT_ULONG_LONG)1 << 5) ///< configure the data available from xnd_get_info() function (xnd_set_visible_info()
|
|
#define XND_PMASK_SS_GET_USERS_LIST ((XLT_ULONG_LONG)1 << 6) ///< get the users list present on xNodus device (xnd_get_user_list_start(), xnd_get_user_list_next()...)
|
|
#define XND_PMASK_SS_GET_USER_INFO ((XLT_ULONG_LONG)1 << 7) ///< collect information releted to a given user (xnd_get_user_info(), xnd_get_current_user_info())
|
|
#define XND_PMASK_SS_CREATE_USER ((XLT_ULONG_LONG)1 << 8) ///< create a user (xnd_create_user())
|
|
#define XND_PMASK_SS_UPDATE_USER ((XLT_ULONG_LONG)1 << 9) ///< update a user (xnd_update_user())
|
|
#define XND_PMASK_SS_DELETE_USER ((XLT_ULONG_LONG)1 << 10) ///< delete a user (xnd_delete_user())
|
|
#define XND_PMASK_SS_SET_USER_KEY ((XLT_ULONG_LONG)1 << 11) ///< set or change a user key (xnd_change_user_key())
|
|
#define XND_PMASK_SS_START_SBL ((XLT_ULONG_LONG)1 << 12) ///< start Secure Boot Loader (xnd_start_sbl())
|
|
#define XND_PMASK_SS_START_SESSION_CHECK ((XLT_ULONG_LONG)1 << 13) ///< start session check (xnd_start_session_check())
|
|
#define XND_PMASK_SS_CONTINUE_SESSION_CHECK ((XLT_ULONG_LONG)1 << 14) ///< continue session check (xnd_continue_session_check())
|
|
#define XND_PMASK_SS_VOLATILE_KEY_SET ((XLT_ULONG_LONG)1 << 15) ///< set the volatile encryption key (xnd_volatile_key_set())
|
|
#define XND_PMASK_SS_VOLATILE_ENCRYPT ((XLT_ULONG_LONG)1 << 16) ///< encryption using the volatile key (xnd_volatile_encrypt())
|
|
#define XND_PMASK_SS_VOLATILE_DECRYPT ((XLT_ULONG_LONG)1 << 17) ///< decryption using the volatile key (xnd_volatile_decrypt())
|
|
#define XND_PMASK_SS_MODULE_OPEN ((XLT_ULONG_LONG)1 << 18) ///< open module (xnd_module_devctx_create())
|
|
#define XND_PMASK_SS_MODULE_CLOSE ((XLT_ULONG_LONG)1 << 19) ///< close module (xnd_module_devctx_release())
|
|
#define XND_PMASK_SS_NV_KEY_SET ((XLT_ULONG_LONG)1 << 20) ///< set a non volatile encryption key (xnd_non_volatile_key_set())
|
|
#define XND_PMASK_SS_NV_CRYPT ((XLT_ULONG_LONG)1 << 21) ///< encryption using a non volatile key (xnd_non_volatile_encrypt())
|
|
#define XND_PMASK_SS_NV_DECRYPT ((XLT_ULONG_LONG)1 << 22) ///< decryption using a non volatile key (xnd_non_volatile_decrypt())
|
|
#define XND_PMASK_SS_CLOSE_ALL_SESSIONS ((XLT_ULONG_LONG)1 << 23) ///< close all open sessions (xnd_close_all_sessions())
|
|
#define XND_PMASK_SS_SET_PERMISSION_MASK ((XLT_ULONG_LONG)1 << 24) ///< allow to set the permission mask (xnd_set_permission_mask())
|
|
#define XND_PMASK_SS_XLIGHT_VIRGINIZE ((XLT_ULONG_LONG)1 << 25) ///< virginize an attached virtual XLight device (xnd_virginize_xlight())
|
|
#define XND_PMASK_SS_GET_RANDOM_VALUES ((XLT_ULONG_LONG)1 << 26) ///< get a true random value (xnd_get_true_random())
|
|
#define XND_PMASK_SS_MODULE_CHALLENGE ((XLT_ULONG_LONG)1 << 27) ///< use module challenge function (xnd_xlt_module_challenge())
|
|
#define XND_PMASK_SS_GET_LOG_LIST ((XLT_ULONG_LONG)1 << 28) ///< allow the execution of the log (xnd_get_log_list_start(), xnd_get_log_list_next()...)
|
|
#define XN_PMASK_SS_GET_USERS_LIST_WITH_INDEX ((XLT_ULONG_LONG)1 << 29) ///< get the extended users list present on xNodus device (xnd_get_user_list_idx_start(), xnd_get_user_list_idx_next()...)
|
|
#define XND_PMASK_SS_XLIGHT_COMMANDS ((XLT_ULONG_LONG)1 << 32) ///< allow to run every XLight command on the virtual XLight connected to the running user
|
|
//\cond NOT_COMMENTED
|
|
#define XND_PMASK_SS_SET_NTP_QUERY ((XLT_ULONG_LONG)1 << 40)
|
|
#define XND_PMASK_SS_SET_TIME ((XLT_ULONG_LONG)1 << 41)
|
|
//\endcond
|
|
//@}
|
|
#define XN_PMASK_SS_XCORE_COMMANDS ((XLT_ULONG_LONG)1 << 48) ///< allow the user of running xCore functions
|
|
|
|
/**
|
|
\ingroup xnodus_defines
|
|
Default value of the permission for the 'Anonymous' user (see \ref xnd_users_types)
|
|
*/
|
|
#define XND_PMASK_USER_ANONYMOUS_DEFAULT (XLT_ULONG_LONG)(XND_PMASK_SS_GET_INFO | \
|
|
XND_PMASK_SS_GET_USER_INFO | \
|
|
XND_PMASK_SS_START_SESSION_CHECK | \
|
|
XND_PMASK_SS_CONTINUE_SESSION_CHECK | \
|
|
XND_PMASK_SS_VOLATILE_KEY_SET | \
|
|
XND_PMASK_SS_VOLATILE_ENCRYPT | \
|
|
XND_PMASK_SS_VOLATILE_DECRYPT | \
|
|
XND_PMASK_SS_MODULE_OPEN | \
|
|
XND_PMASK_SS_MODULE_CLOSE | \
|
|
XND_PMASK_SS_NV_CRYPT | \
|
|
XND_PMASK_SS_NV_DECRYPT | \
|
|
XND_PMASK_SS_GET_RANDOM_VALUES | \
|
|
XND_PMASK_SS_MODULE_CHALLENGE | \
|
|
XND_PMASK_SS_XLIGHT_COMMANDS)
|
|
|
|
|
|
//#define XND_PMASK_USER_ANONYMOUS_DEFAULT (XLT_ULONG_LONG)(XND_PMASK_SS_GET_INFO | XND_PMASK_SS_SET_NETWORK | XND_PMASK_SS_GET_USER_INFO | XND_PMASK_SS_START_SESSION_CHECK | \
|
|
// XND_PMASK_SS_CONTINUE_SESSION_CHECK | XND_PMASK_SS_VOLATILE_KEY_SET | XND_PMASK_SS_VOLATILE_ENCRYPT | XND_PMASK_SS_VOLATILE_DECRYPT | XND_PMASK_SS_MODULE_OPEN | \
|
|
// XND_PMASK_SS_MODULE_CLOSE | XND_PMASK_SS_NV_CRYPT | XND_PMASK_SS_NV_DECRYPT | XND_PMASK_SS_GET_RANDOM_VALUES | XND_PMASK_SS_MODULE_CHALLENGE | XND_PMASK_SS_XLIGHT_COMMANDS)
|
|
|
|
|
|
|
|
/**
|
|
\ingroup xnodus_defines
|
|
Default value of the permission for the user with identity.
|
|
*/
|
|
#define XND_PMASK_USER_DEFAULT XND_PMASK_USER_ANONYMOUS_DEFAULT
|
|
|
|
|
|
/**
|
|
\ingroup xnodus_defines
|
|
\defgroup xnd_user_significant_mask User info significant values mask
|
|
|
|
Mask values for the -set_values_mask- entry of the ::XND_USER_INFO structure
|
|
Note that the entries user_type, user_name and set_values_mask are always set and not included in the significant mask
|
|
*/
|
|
#define XND_USER_SIGNIFICANT_MASK_EXPIRATION ((unsigned int)1 << 0) ///< the 'license_expiration_time' entry in ::XND_USER_INFO is significant
|
|
#define XND_USER_SIGNIFICANT_MASK_LICENSES ((unsigned int)1 << 1) ///< the 'num_licenses' entry in ::XND_USER_INFO is significant
|
|
#define XND_USER_SIGNIFICANT_MASK_INSTANCES ((unsigned int)1 << 2) ///< the 'max_instances' entry in ::XND_USER_INFO is significant
|
|
#define XND_USER_SIGNIFICANT_MASK_MODULE ((unsigned int)1 << 3) ///< the 'num_licenses_for_module' entry in ::XND_USER_INFO is significant
|
|
#define XND_USER_SIGNIFICANT_MASK_MODULE_EXPIRATION ((unsigned int)1 << 4) ///< the 'module_license_expiration_time' entry in ::XND_USER_INFO is significant
|
|
#define XND_USER_SIGNIFICANT_MASK_XLIGHT_INSTANCE ((unsigned int)1 << 5) ///< the 'xlight_index' entry in ::XND_USER_INFO is significant
|
|
#define XND_USER_SIGNIFICANT_MASK_PERMISSION_MASK ((unsigned int)1 << 6) ///< the 'permission_mask' entry in ::XND_USER_INFO is significant
|
|
#define XND_USER_SIGNIFICANT_MASK_KEY ((unsigned int)1 << 7) ///< 'key_type', 'key_len' and 'key' entries in ::XND_USER_INFO are significant
|
|
#define XND_USER_SIGNIFICANT_MASK_CURRENT_LICENSES ((unsigned int)1 << 31) ///< the 'current_licenses' entry in ::XND_USER_INFO is significant
|
|
#define XND_USER_SIGNIFICANT_MASK_CURRENT_LICENSES_IN_MODULES ((unsigned int)1 << 30) ///< the 'current_licenses_in_module' entry in ::XND_USER_INFO is significant
|
|
|
|
/**
|
|
Every field in ::XND_USER_INFO is significant.
|
|
|
|
::XND_USER_SIGNIFICANT_MASK_CURRENT_LICENSES and ::XND_USER_SIGNIFICANT_MASK_CURRENT_LICENSES_IN_MODULES are excluded.
|
|
*/
|
|
#define XND_USER_SIGNIFICANT_MASK_ALL (XND_USER_SIGNIFICANT_MASK_EXPIRATION | XND_USER_SIGNIFICANT_MASK_LICENSES | XND_USER_SIGNIFICANT_MASK_INSTANCES | XND_USER_SIGNIFICANT_MASK_MODULE | XND_USER_SIGNIFICANT_MASK_MODULE_EXPIRATION | XND_USER_SIGNIFICANT_MASK_XLIGHT_INSTANCE | XND_USER_SIGNIFICANT_MASK_PERMISSION_MASK | XND_USER_SIGNIFICANT_MASK_KEY | XND_USER_SIGNIFICANT_MASK_CURRENT_LICENSES | XND_USER_SIGNIFICANT_MASK_CURRENT_LICENSES_IN_MODULES)
|
|
|
|
/**
|
|
Every field in ::XND_USER_INFO is significant except the key data
|
|
|
|
::XND_USER_SIGNIFICANT_MASK_CURRENT_LICENSES and ::XND_USER_SIGNIFICANT_MASK_CURRENT_LICENSES_IN_MODULES are excluded.
|
|
*/
|
|
#define XND_USER_SIGNIFICANT_MASK_ALL_NO_KEY (XND_USER_SIGNIFICANT_MASK_EXPIRATION | XND_USER_SIGNIFICANT_MASK_LICENSES | XND_USER_SIGNIFICANT_MASK_INSTANCES | XND_USER_SIGNIFICANT_MASK_MODULE | XND_USER_SIGNIFICANT_MASK_MODULE_EXPIRATION | XND_USER_SIGNIFICANT_MASK_XLIGHT_INSTANCE | XND_USER_SIGNIFICANT_MASK_PERMISSION_MASK | XND_USER_SIGNIFICANT_MASK_CURRENT_LICENSES | XND_USER_SIGNIFICANT_MASK_CURRENT_LICENSES_IN_MODULES)
|
|
|
|
/**
|
|
\ingroup xnodus_defines
|
|
User information data structure
|
|
*/
|
|
typedef struct _XND_USER_INFO{
|
|
unsigned int user_type; ///< user type
|
|
unsigned char user_name[XND_USER_NAME_LEN]; ///< user name
|
|
unsigned int set_values_mask; ///< mask of the significant values of this structure (see \ref xnd_user_significant_mask).
|
|
unsigned int num_licenses; ///< number of licenses of the user (when a user has more than a license it is also identified as a group)
|
|
unsigned int max_instances; ///< maximum number of instances the user may open simultaneously from a computer
|
|
unsigned int current_licenses; ///< current licenses in use
|
|
unsigned int license_expiration_time; ///< license expiration time expressed in unix time
|
|
unsigned int num_licenses_for_module[XND_MAX_NUM_MODULES]; ///< number of licenses for each module (identified by the position in the array)
|
|
unsigned int module_license_expiration_time[XND_MAX_NUM_MODULES]; ///< expiration time of the module
|
|
unsigned int current_licenses_in_module[XND_MAX_NUM_MODULES]; ///< current number of users of a module consumed by the user (identified by the position in the array). This entry is meaningful only retrieving data from the device
|
|
unsigned int xlight_index; ///< index of the associated XLight virtual device
|
|
unsigned int _unused;///<unused
|
|
XLT_ULONG_LONG permission_mask; ///< permission mask on the functions the user is allowed to run. This entry takes its values from a sequence of bitwise or from \ref xnd_permision_mask
|
|
unsigned int key_type; ///< type of cryptographic key owned by the user (values from \ref xnd_info_key_type).
|
|
unsigned int key_len; ///< length of cryptographic key owned by the user
|
|
unsigned char key[XND_RSA_4096_PRIV_KEY_SIZE];///< cryptographic key owned by the user
|
|
unsigned int _unused2;///<unused
|
|
}XND_USER_INFO;
|
|
typedef XND_USER_INFO *P_XND_USER_INFO; ///< pointer to ::XND_USER_INFO type
|
|
|
|
//\ingroup xnodus_main_functions
|
|
/**
|
|
\ingroup xnd_devctx_session
|
|
Create an xNodus environment handle.
|
|
The basic xNodus modules and startup operation of the library are done by this call.
|
|
\return the handle to the xNodus environment
|
|
\parblock
|
|
\note The original XLight functions call xnd_xlt_env_create() implicitly.
|
|
\endparblock
|
|
\parblock
|
|
\remark The returned ::XND_XLT_ENV handle must be released calling xnd_xlt_env_free().
|
|
\endparblock
|
|
*/
|
|
XND_LINK XND_XLT_ENV XND_API xnd_xlt_env_create();
|
|
|
|
//\ingroup xnodus_main_functions
|
|
/**
|
|
\ingroup xnd_devctx_session
|
|
Complete the execution and free the memory allocated by xnd_xlt_env_create()
|
|
\param[in] env the xNodus environment handle to be freed.
|
|
*/
|
|
XND_LINK int XND_API xnd_xlt_env_free(XND_XLT_ENV env);
|
|
|
|
//\cond NOT_COMMENTED
|
|
XND_LINK XND_XLT_ENV XND_API xnd_xlt_env_acquire(XND_XLT_ENV env);
|
|
XND_LINK int XND_API xnd_xlt_env_release(XND_XLT_ENV env);
|
|
//\endcond
|
|
|
|
/**
|
|
\ingroup xnodus_find_devices
|
|
Start a search of one or more xNodus device in the local network.
|
|
See \ref searching_xnodus for an usage example.
|
|
\param[in] env xNodus environment handle (see xnd_xlt_env_create()).
|
|
\param[in] remember_found_devices remember the address of xNodus device found to speed up search in future searches.
|
|
\param[in] port the tcp-ip port used by xNodus.
|
|
\param[in] label point to a buffer containing the label of the device. This entry can be set to <i>0</i>
|
|
\param[out] p_status points to an integer that will receive the status of the operation: ::XND_ERROR_SUCCESS on success, an \ref xnodus_errors "error code" on failure.
|
|
\return a ::XND_DEVICE_FIND handle on success, zero otherwise, p_status will point to the occurred error.
|
|
|
|
\remark If the entry <i>label</i> is specified only xNodus devices with that label (i.e. its identification name) are found.
|
|
|
|
\remark The <i>port</i> entry needs to be specified only if the argument <i>label</i> is set. If <i>port</i> has an uncorrect value it is not possible verify the label of the xNodus device.
|
|
|
|
\remark The <i>remember_found_devices</i> instruct the API to keep track of the found device in the registry to speed up successive device search.
|
|
|
|
\remark The memory referenced by the ::XND_DEVICE_FIND handle returned by this function must be freed with xnd_device_find_stop().
|
|
\see xnd_device_find_next(), xnd_device_find_finalize().
|
|
*/
|
|
XND_LINK XND_DEVICE_FIND XND_API xnd_device_find_create(XND_XLT_ENV env, unsigned int remember_found_devices, OPT unsigned short port, OPT const unsigned char* label, OPT OUT int* p_status);
|
|
|
|
//\cond NOT_COMMENTED
|
|
XND_LINK XND_DEVICE_FIND XND_API xnd_device_find_create2(XND_XLT_ENV env, unsigned int remember_found_devices, XND_IN_ADDR hint_subnet, XND_IN_ADDR hint_subnet_mask, OPT unsigned short port, OPT const unsigned char* label, OPT OUT int* p_status);
|
|
//\endcond
|
|
|
|
/**
|
|
\ingroup xnodus_find_devices
|
|
Return the address of an xNodus device found in the local network.
|
|
See \ref searching_xnodus for an usage example.
|
|
\param[in] ctx a ::XND_DEVICE_FIND handle generated by xnd_device_find_create().
|
|
\param[in] timeout_msec maximum time allowed to find an xNodus device.
|
|
\param[out] sock_addr points to structure receiving the IPv4 address of the found device.
|
|
\return ::XND_ERROR_SUCCESS on success, an \ref xnodus_errors "error code" on failure. If the timeout is expired but the network is not completely explored (so some devices may be still found) the value XND_ERROR_FIND_NOT_FOUND_YET is returned.
|
|
|
|
\see xnd_device_find_create(), xnd_device_find_finalize().
|
|
*/
|
|
XND_LINK int XND_API xnd_device_find_next(XND_DEVICE_FIND ctx, unsigned int timeout_msec, OUT XND_IN_ADDR* sock_addr);
|
|
|
|
/**
|
|
\ingroup xnodus_find_devices
|
|
Stop the xNodus device search.
|
|
See \ref searching_xnodus for an usage example.
|
|
\param[in] ctx a ::XND_DEVICE_FIND handle generated by xnd_device_find_create().
|
|
\remark This is an optional function, it helps xnd_in_device_find_finalize() to run faster if called many milliseconds before it.
|
|
This function instructs the searching threads launched by xnd_device_find_create() to terminate the xNodus device search.
|
|
*/
|
|
XND_LINK void XND_API xnd_device_find_stop(XND_DEVICE_FIND ctx);
|
|
|
|
/**
|
|
\ingroup xnodus_find_devices
|
|
Complete an xNodus device search.
|
|
See \ref searching_xnodus for an usage example.
|
|
\param[in] ctx a XND_DEVICE_FIND handle generated by xnd_device_find_create().
|
|
\see xnd_device_find_create(), xnd_device_find_next().
|
|
*/
|
|
XND_LINK void XND_API xnd_device_find_finalize(XND_DEVICE_FIND ctx);
|
|
|
|
|
|
|
|
/////////////////////////////////////////
|
|
// network data functions (possibly in future IPV6 support)
|
|
|
|
//network data
|
|
|
|
/**
|
|
\defgroup xnd_protocol_type Protocol types
|
|
\ingroup xnodus_defines
|
|
|
|
Type of protocol to be used during the communication to the xNodus device. At present only one protocol based on TCP-IP is supported.
|
|
|
|
@{
|
|
*/
|
|
#define XND_NET_PROTOCOL_UNKNOWN 0 ///< unknown protocol
|
|
#define XND_NET_PROTOCOL_TCP 1 ///< TCP basic xNodus protocol
|
|
#define XND_NET_PROTOCOL_UDP 2 ///< UDP basic xNodus protocol (default)
|
|
|
|
//@}
|
|
|
|
|
|
/**
|
|
\ingroup xnodus_net_func
|
|
Create a ::XND_NET_DATA handle.
|
|
\param[in] env xNodus environment handle (see xnd_xlt_env_create()).
|
|
\param[in] addr_port a pointer to the null terminated name of the host to resolve and the port expressed as \<address\>.\<port\>.
|
|
\param[in] protocol_type the communication protocol type to be used. If the value is set to zero the default ::XND_NET_PROTOCOL_UDP is used.
|
|
\param[in] recv_to_msec the timeout for getting answer from the xNodus device.
|
|
\param[out] p_status points to an integer that will receive the status of the operation: ::XND_ERROR_SUCCESS on success, an \ref xnodus_errors "error code" on failure.
|
|
\return a ::XND_NET_DATA handle.
|
|
\remark The argument addr_port is a string of the form \<address\>.\<port\>, for instance: 192.168.0.125:15678 or foo.example.com:15600.
|
|
\remark The returned ::XND_NET_DATA handle must be freed calling xnd_net_data_release().
|
|
\remark Setting recv_to_msec to 0 the default value (5000 milliseconds) is used.
|
|
\see xnd_net_data_release(), xnd_net_data_acquire()
|
|
*/
|
|
XND_LINK XND_NET_DATA XND_API xnd_net_data_create_from_addr_port(XND_XLT_ENV env, const char* addr_port, OPT unsigned int protocol_type, OPT unsigned int recv_to_msec, OPT OUT int* p_status);
|
|
|
|
/**
|
|
\ingroup xnodus_net_func
|
|
Create a ::XND_NET_DATA handle and immediately resolve the address.
|
|
\param[in] env xNodus environment handle (see xnd_xlt_env_create()).
|
|
\param[in] addr_port a pointer to the null terminated name of the host to resolve and the port expressed as \<address\>.\<port\>.
|
|
\param[in] protocol_type the communication protocol type to be used. If set to zero the default value is used (::XND_NET_PROTOCOL_UDP).
|
|
\param[in] recv_to_msec the timeout for getting answer from the xNodus device. If set to zero the default value is used (5000 msec).
|
|
\param[out] p_status points to an integer that will receive the status of the operation: ::XND_ERROR_SUCCESS on success, an \ref xnodus_errors "error code" on failure.
|
|
\return a ::XND_NET_DATA handle.
|
|
|
|
\remark This command is similar to xnd_net_data_create_from_addr_port() but it immediately resolve the address. If it is not possible the function immediately fails.
|
|
\remark The returned ::XND_NET_DATA handle must be freed calling xnd_net_data_release().
|
|
|
|
\see xnd_net_data_create_from_addr_port().
|
|
*/
|
|
XND_LINK XND_NET_DATA XND_API xnd_net_data_create_resolving_addr_port(XND_XLT_ENV env, const char* addr_port, OPT unsigned int protocol_type, OPT unsigned int recv_to_msec, OPT OUT int* p_status);
|
|
|
|
/**
|
|
\ingroup xnodus_net_func
|
|
Create a ::XND_NET_DATA handle. It represent an xNodus device in the local network. The address is resolved when the xnd_net_data_get_addr() function is called.
|
|
\param[in] env xNodus environment handle (see xnd_xlt_env_create()).
|
|
\param[in] port the TCP/IP port used by the searched xNodus device.
|
|
\param[in] label the xNodus label of the searched device. If a NULL pointer is set the label is ignored and any found device is considered regardless the label.
|
|
\param[in] search_timeout_msec the maximum time expressed in millisecond that the searching procedure may take. If this value is set to zero there is no such limit.
|
|
\param[in] protocol_type the communication protocol type to be used. If set to zero the default value is used (::XND_NET_PROTOCOL_UDP).
|
|
\param[in] recv_to_msec the timeout for getting answer from the xNodus device. If set to zero the default value is used (5000 msec).
|
|
\param[out] p_status points to an integer that will receive the status of the operation: ::XND_ERROR_SUCCESS on success, an \ref xnodus_errors "error code" on failure.
|
|
\return a ::XND_NET_DATA handle.
|
|
\remark The returned ::XND_NET_DATA handle must be freed calling xnd_net_data_release().
|
|
\see xnd_net_data_create_from_addr_port().
|
|
*/
|
|
XND_LINK XND_NET_DATA XND_API xnd_net_data_create_local_search(XND_XLT_ENV env, unsigned short port, OPT const unsigned char* label, OPT unsigned int search_timeout_msec, OPT unsigned int protocol_type, OPT unsigned int recv_to_msec, OPT OUT int* p_status);
|
|
|
|
/**
|
|
\ingroup xnodus_net_func
|
|
Create a ::XND_NET_DATA handle and immediately search an xNodus device in the local network.
|
|
\param[in] env xNodus environment handle (see xnd_xlt_env_create()).
|
|
\param[in] port the TCP/IP port used by the searched xNodus device.
|
|
\param[in] label the xNodus label of the searched device. If a NULL pointer is set the label is ignored and any found device is considered regardless the label.
|
|
\param[in] search_timeout_msec the maximum time expressed in millisecond that the searching procedure may take. If this value is set to zero there is no such limit.
|
|
\param[in] protocol_type the communication protocol type to be used. If set to zero the default value is used (::XND_NET_PROTOCOL_UDP).
|
|
\param[in] recv_to_msec the timeout for getting answer from the xNodus device. If set to zero the default value is used (5000 msec).
|
|
\param[out] p_status points to an integer that will receive the status of the operation: ::XND_ERROR_SUCCESS on success, an \ref xnodus_errors "error code" on failure.
|
|
\return a ::XND_NET_DATA handle.
|
|
|
|
\remark This command is similar to xnd_net_data_create_local_search() but it immediately resolve the address. If it is not possible the
|
|
function immediately fails.
|
|
\remark The returned ::XND_NET_DATA handle must be freed calling xnd_net_data_release().
|
|
\see xnd_net_data_create_local_search(), xnd_net_data_create_from_addr_port().
|
|
*/
|
|
XND_LINK XND_NET_DATA XND_API xnd_net_data_create_resolving_local_search(XND_XLT_ENV env, unsigned short port, OPT const unsigned char* label, OPT unsigned int search_timeout_msec, OPT unsigned int protocol_type, OPT unsigned int recv_to_msec, OPT OUT int* p_status);
|
|
|
|
/**
|
|
\ingroup xnodus_net_func
|
|
Create a XND_NET_DATA handle from an IPv4 address.
|
|
\param[in] env xNodus environment handle (see xnd_xlt_env_create()).
|
|
\param[in] sock_addr a pointer to a ::XND_SOCK_ADDR struct.
|
|
\param[in] protocol_type the communication protocol type to be used. If set to zero the default value is used (::XND_NET_PROTOCOL_UDP).
|
|
\param[in] recv_to_msec the timeout for getting answer from the xNodus device. If set to zero the default value is used (5000 msec).
|
|
\param[out] p_status points to an integer that will receive the status of the operation: ::XND_ERROR_SUCCESS on success, an \ref xnodus_errors "error code" on failure.
|
|
\return a ::XND_NET_DATA handle.
|
|
\remark The returned ::XND_NET_DATA handle must be freed calling xnd_net_data_release().
|
|
*/
|
|
XND_LINK XND_NET_DATA XND_API xnd_net_data_create_from_sock_addr(XND_XLT_ENV env, const XND_SOCK_ADDR* sock_addr, OPT unsigned int protocol_type, OPT unsigned int recv_to_msec, OPT OUT int* p_status);
|
|
|
|
/**
|
|
\ingroup xnodus_net_func
|
|
Acquire a net data object pointed by a ::XND_NET_DATA handle (see \ref xnd_create_acquire_release).
|
|
\param[in] ctx a ::XND_NET_DATA handle referencing the object to acquire.
|
|
\return on success a reference to the input ::XND_NET_DATA handle, '0' otherwise.
|
|
\remark The reference to the ::XND_NET_DATA handle obtained by this function must be freed calling xnd_net_data_release().
|
|
*/
|
|
XND_LINK XND_NET_DATA XND_API xnd_net_data_acquire(XND_NET_DATA ctx);
|
|
|
|
/**
|
|
\ingroup xnodus_net_func
|
|
Release a net data object pointed by a ::XND_NET_DATA handle (see \ref xnd_create_acquire_release).
|
|
\param[in] ctx the ::XND_NET_DATA handle referencing to the object to release.
|
|
\return ::XND_ERROR_SUCCESS on success, an \ref xnodus_errors "error code" on failure, and ::XND_RELEASE_STILL_REFERENCED if there are still reference to the object.
|
|
\remark When the reference to the object represented by the ::XND_NET_DATA are.
|
|
all removed the object are automatically freed.
|
|
\remark When ::XND_RELEASE_STILL_REFERENCED are returned the operation may be considered as correctly completed and no further action must be taken.
|
|
This is just a way to inform that there is at least one reference to the object and that the object will be deleted only when the last xnd_net_data_release() call will be issued.
|
|
*/
|
|
XND_LINK int XND_API xnd_net_data_release(XND_NET_DATA ctx);
|
|
|
|
/**
|
|
\ingroup xnodus_net_func
|
|
Return the IPv4 address and port number related to a ::XND_NET_DATA handle.
|
|
\param[in] ctx the ::XND_NET_DATA handle referencing the object to release.
|
|
\param[out] sock_addr points to a ::XND_SOCK_ADDR structure that will receive the address and port related to the handle.
|
|
\return ::XND_ERROR_SUCCESS on success, an \ref xnodus_errors "error code" on failure.
|
|
*/
|
|
XND_LINK int XND_API xnd_net_data_get_addr(XND_NET_DATA ctx, P_XND_SOCK_ADDR sock_addr);
|
|
|
|
//\cond NOT_COMMENTED
|
|
XND_LINK unsigned char* XND_API xnd_net_data_to_bytes_alloc(XND_NET_DATA ctx, unsigned int* p_len);
|
|
XND_LINK XND_NET_DATA XND_API xnd_net_data_from_bytes_create(XND_XLT_ENV env, const unsigned char* data, unsigned int data_len);
|
|
//\endcond
|
|
|
|
|
|
|
|
//xnodus_net_func
|
|
|
|
/////////////////////////////////////////////////////////////////////////////////////////
|
|
//Key types for key data
|
|
|
|
/** \defgroup xnd_key_data_types Cryptographic key types for key data objects
|
|
\ingroup xnodus_defines
|
|
Cryptographic key types for ::XND_KEY_DATA objects
|
|
@{
|
|
*/
|
|
#ifndef XND_KD_KEY_TYPE_NO_KEY
|
|
#define XND_KD_KEY_TYPE_NO_KEY 0 ///< no key
|
|
#define XND_KD_KEY_TYPE_AES 1 ///< AES 256 key type
|
|
#define XND_KD_KEY_TYPE_RSA_PUB 2 ///< RSA public key (of any size)
|
|
#define XND_KD_KEY_TYPE_RSA_PRIV 3 ///< RSA private key (of any size)
|
|
#endif //XND_KD_KEY_TYPE_NO_KEY
|
|
//@} //xnd_key_data_types
|
|
|
|
//SERVICE FUNCTIONS TO BUILD KEY DATA
|
|
|
|
|
|
//xnodus_crypto_key_man
|
|
|
|
/**
|
|
\ingroup xnodus_crypto_key_man
|
|
Create a key data object from a string representation of the key.
|
|
\param[in] env xNodus environment handle (see xnd_xlt_env_create()).
|
|
\param[in] key_blob_data points string containing the key in encoded form.
|
|
\param[in] wrap_key_string points to a string used as password for decrypting 'key_blob_data'. This argument is optional and can be set to 0.
|
|
\param[out] p_status points to an integer that will receive the status of the operation: ::XND_ERROR_SUCCESS on success, an \ref xnodus_errors "error code" on failure.
|
|
\return a ::XND_KEY_DATA handle which points to an allocated key data representing the 'key_blob_data' entry. Use xnd_keydata_release() to release the returned object.
|
|
\note 'key_blob_data' is a base 64 representation of a key object. Such representation can be encrypted and in this case the argument 'wrap_key_string' must point to the unwrapping key.
|
|
\see \ref xnd_key_data.
|
|
*/
|
|
XND_LINK XND_KEY_DATA XND_API xnd_keydata_from_keyblob_create(XND_XLT_ENV env, const char* key_blob_data, OPT const char* wrap_key_string, OPT OUT int* p_status);
|
|
|
|
/**
|
|
\ingroup xnodus_crypto_key_man
|
|
Create a key data object from a string representation of the key.
|
|
\param[in] env xNodus environment handle (see xnd_xlt_env_create()).
|
|
\param[in] key_blob_data points string containing the key in encoded form.
|
|
\param[in] wrap_key points to a ::XND_KEY_DATA object containing the cryptographic key for decrypting 'key_blob_data'. This argument is optional and can be set to 0.
|
|
\param[out] p_status points to an integer that will receive the status of the operation: ::XND_ERROR_SUCCESS on success, an \ref xnodus_errors "error code" on failure.
|
|
\return a ::XND_KEY_DATA handle which points to an allocated key data representing the 'key_blob_data' entry. Use xnd_keydata_release() to release the returned object.
|
|
\note 'key_blob_data' is a base 64 representation of a key object. Such representation can be encrypted and in this case the argument 'wrap_key' must point to the unwrapping key.
|
|
\see \ref xnd_key_data.
|
|
*/
|
|
XND_LINK XND_KEY_DATA XND_API xnd_keydata_from_keyblob_create2(XND_XLT_ENV env, const char* key_blob_data, XND_KEY_DATA wrap_key, OPT OUT int* p_status);
|
|
|
|
/**
|
|
\ingroup xnodus_crypto_key_man
|
|
Create a key data object from a key represented in XLight RSA format (see \ref xnd_key_data).
|
|
\param[in] env xNodus environment handle (see xnd_xlt_env_create()).
|
|
\param[in] priv_key points to a buffer containing the RSA private key specified in XLight format.
|
|
\param[in] priv_key_len the length of the key pointed by 'priv_key' argument.
|
|
\param[out] p_status points to an integer that will receive the status of the operation: ::XND_ERROR_SUCCESS on success, an \ref xnodus_errors "error code" on failure.
|
|
\return a ::XND_KEY_DATA handle which points to an allocated key data representing the passed input. Use xnd_keydata_release() to release the returned object.
|
|
\see \ref xnd_key_data.
|
|
*/
|
|
XND_LINK XND_KEY_DATA XND_API xnd_keydata_rsa_xlt_priv_key_create(XND_XLT_ENV env, const unsigned char* priv_key, unsigned int priv_key_len, OPT OUT int* p_status);
|
|
|
|
/**
|
|
\ingroup xnodus_crypto_key_man
|
|
Create a key data object from a key represented in PQE format (see \ref xnd_key_data).
|
|
\param[in] env xNodus environment handle (see xnd_xlt_env_create()).
|
|
\param[in] priv_key points to a buffer containing the RSA private key specified in PQE format.
|
|
\param[in] priv_key_len the length of the key pointed by 'priv_key' argument.
|
|
\param[out] p_status points to an integer that will receive the status of the operation: ::XND_ERROR_SUCCESS on success, an \ref xnodus_errors "error code" on failure.
|
|
\return a ::XND_KEY_DATA handle which points to an allocated key data representing the passed input. Use xnd_keydata_release() to release the returned object.
|
|
\see \ref xnd_key_data.
|
|
*/
|
|
XND_LINK XND_KEY_DATA XND_API xnd_keydata_rsa_pqe_priv_key_create(XND_XLT_ENV env, const unsigned char* priv_key, unsigned int priv_key_len, OPT OUT int* p_status);
|
|
|
|
/**
|
|
\ingroup xnodus_crypto_key_man
|
|
Check if a supposed RSA private key is correct.
|
|
|
|
It is not tested only the type of the object, but the key values are checked.
|
|
\param[in] key_data the ::XND_KEY_DATA handle referencing to the key object to check.
|
|
\return ::XND_ERROR_SUCCESS on success, an \ref xnodus_errors "error code" on failure.
|
|
\see \ref xnd_key_data.
|
|
*/
|
|
XND_LINK int XND_API xnd_keydata_rsa_priv_key_is_correct(XND_KEY_DATA key_data);
|
|
|
|
/**
|
|
\ingroup xnodus_crypto_key_man
|
|
Create a key data object of a RSA public key derived from its private key.
|
|
\param[in] key_data the ::XND_KEY_DATA handle of a private RSA key
|
|
\param[out] p_status points to an integer that will receive the status of the operation: ::XND_ERROR_SUCCESS on success, an \ref xnodus_errors "error code" on failure.
|
|
\return a ::XND_KEY_DATA handle which points to the allocated key data representing the public key. Use xnd_keydata_release() to release the returned object.
|
|
\see \ref xnd_key_data.
|
|
*/
|
|
XND_LINK XND_KEY_DATA XND_API xnd_keydata_rsa_pub_key_from_priv_create(XND_KEY_DATA key_data, OPT OUT int* p_status);
|
|
|
|
/**
|
|
\ingroup xnodus_crypto_key_man
|
|
Create a key data object of a RSA public from a buffer representation of the key (see \ref xnd_key_data).
|
|
\param[in] env xNodus environment handle (see xnd_xlt_env_create()).
|
|
\param[in] pub_key points to a buffer containing the RSA public key in buffer format.
|
|
\param[in] pub_key_len the length in bytes of the buffer pointed by 'pub_key'.
|
|
\param[out] p_status points to an integer that will receive the status of the operation: ::XND_ERROR_SUCCESS on success, an \ref xnodus_errors "error code" on failure.
|
|
\return a ::XND_KEY_DATA handle which points to the allocated key data representing the public key. Use xnd_keydata_release() to release the returned object.
|
|
\see \ref xnd_key_data.
|
|
*/
|
|
XND_LINK XND_KEY_DATA XND_API xnd_keydata_rsa_pub_key_create(XND_XLT_ENV env, const unsigned char* pub_key, unsigned int pub_key_len, OPT OUT int* p_status);
|
|
|
|
/**
|
|
\ingroup xnodus_crypto_key_man
|
|
Create a key data object representing an AES key (see \ref xnd_key_data).
|
|
\param[in] env xNodus environment handle (see xnd_xlt_env_create()).
|
|
\param[in] key points to a 32 byte buffer containing the AES key.
|
|
\param[out] p_status points to an integer that will receive the status of the operation: ::XND_ERROR_SUCCESS on success, an \ref xnodus_errors "error code" on failure.
|
|
\return a ::XND_KEY_DATA handle which points to the allocated key data representing the symmetric AES key. Use xnd_keydata_release() to release the returned object.
|
|
\see \ref xnd_key_data.
|
|
*/
|
|
XND_LINK XND_KEY_DATA XND_API xnd_keydata_aes_key_create(XND_XLT_ENV env, const unsigned char* key, OPT OUT int* p_status);
|
|
|
|
/**
|
|
\ingroup xnodus_crypto_key_man
|
|
Create a key data object representing an AES key derived from a printable string used as a password for unwrapping the user data keys (see \ref xnd_deferring_wrap_key).
|
|
\param[in] env xNodus environment handle (see xnd_xlt_env_create()).
|
|
\param[in] wrap_key_string the wrapping string
|
|
\param[out] p_status points to an integer that will receive the status of the operation: ::XND_ERROR_SUCCESS on success, an \ref xnodus_errors "error code" on failure.
|
|
\return a ::XND_KEY_DATA handle which points to the allocated key data representing the symmetric AES key used to unwrap user data. Use xnd_keydata_release() to release the returned object.
|
|
\see \ref xnd_key_data.
|
|
*/
|
|
XND_LINK XND_KEY_DATA XND_API xnd_keydata_create_from_wrapstring(XND_XLT_ENV env, const char* wrap_key_string, OPT OUT int* p_status);
|
|
|
|
/**
|
|
\ingroup xnodus_crypto_key_man
|
|
Acquire a key data object pointed by a ::XND_KEY_DATA handle (see \ref xnd_create_acquire_release).
|
|
\param[in] key_data the ::XND_KEY_DATA handle referencing to the object to acquire.
|
|
\return the 'key_data' handle to the object on success, '0' on error.
|
|
\remark The reference to the ::XND_KEY_DATA handle obtained by this function must be freed calling xnd_keydata_release().
|
|
*/
|
|
XND_LINK XND_KEY_DATA XND_API xnd_keydata_acquire(XND_KEY_DATA key_data);
|
|
|
|
/**
|
|
\ingroup xnodus_crypto_key_man
|
|
Release a key data object pointed by a ::XND_KEY_DATA handle (see \ref xnd_create_acquire_release).
|
|
\param[in] key_data the ::XND_KEY_DATA handle referencing to the object to release.
|
|
\return ::XND_ERROR_SUCCESS on success, an \ref xnodus_errors "error code" on failure, and ::XND_RELEASE_STILL_REFERENCED if there are still reference to the object.
|
|
*/
|
|
XND_LINK int XND_API xnd_keydata_release(XND_KEY_DATA key_data);
|
|
|
|
/**
|
|
\ingroup xnodus_crypto_key_man
|
|
Return the type of the key contained in the object.
|
|
\param[in] key_data the ::XND_KEY_DATA handle referencing to the object.
|
|
\return a value in \ref xnd_key_data_types to specify the type of the key
|
|
*/
|
|
XND_LINK unsigned int XND_API xnd_keydata_get_type(XND_KEY_DATA key_data);
|
|
|
|
/**
|
|
\ingroup xnodus_crypto_key_man
|
|
Return the type of the key contained in the object expressing such value from \ref xnd_info_key_type values.
|
|
\param[in] key_data the ::XND_KEY_DATA handle referencing to the object.
|
|
\return a value in \ref xnd_info_key_type to specify the type of the key
|
|
*/
|
|
XND_LINK unsigned int XND_API xnd_keydata_get_info_type(XND_KEY_DATA key_data);
|
|
|
|
/**
|
|
\ingroup xnodus_crypto_key_man
|
|
Create a key data object from the formatted value returned by the 'info' structure xNodus (::XND_INFO and ::XND_USER_INFO).
|
|
\param[in] env xNodus environment handle (see xnd_xlt_env_create()).
|
|
\param[in] info_key_type a value from \ref xnd_info_key_type.
|
|
\param[in] key points to a buffer containing the formatted key expressed with type 'info_key_type'.
|
|
\param[in] key_len the length in bytes of the buffer pointed by 'key'.
|
|
\param[out] p_status points to an integer that will receive the status of the operation: ::XND_ERROR_SUCCESS on success, an \ref xnodus_errors "error code" on failure.
|
|
\return a ::XND_KEY_DATA handle which points to the allocated key data representing the key. Use xnd_keydata_release() to release the returned object.
|
|
\see \ref xnd_key_data.
|
|
*/
|
|
XND_LINK XND_KEY_DATA XND_API xnd_keydata_create_from_keyinfo(XND_XLT_ENV env, unsigned int info_key_type, const unsigned char* key, unsigned int key_len, OPT OUT int* p_status);
|
|
|
|
/**
|
|
\ingroup xnodus_crypto_key_man
|
|
Return the AES key from a key data object.
|
|
\param[in] key_data the handle of type ::XND_KEY_DATA which points to the key data object.
|
|
\param[out] key points to a buffer that will receive the AES key.
|
|
\param[in] key_size the size in bytes of the buffer pointed by 'key'.
|
|
\param[out] p_key_len points to an unsigned integer which will receive the length of the AES key (always 32). This pointer may be set to 0.
|
|
\return ::XND_ERROR_SUCCESS on success, an \ref xnodus_errors "error code" on failure, if the key contained in the object is not an AES key the function fails with error ::XLT_ERROR_INVALID_STATE.
|
|
\remark The unsigned integer pointed by 'p_key_len' receive the size of the key even if key_size is shorter and the function fails.
|
|
\see \ref xnd_key_data.
|
|
*/
|
|
XND_LINK int XND_API xnd_keydata_get_as_aes_key(XND_KEY_DATA key_data, OUT unsigned char* key, unsigned int key_size, unsigned int* p_key_len);
|
|
|
|
/**
|
|
\ingroup xnodus_crypto_key_man
|
|
Return the public RSA key from a key data object.
|
|
\param[in] key_data the handle of type ::XND_KEY_DATA which points to the key data object.
|
|
\param[out] key points to a buffer that will receive the public RSA key.
|
|
\param[in] key_size the size in bytes of the buffer pointed by 'key'.
|
|
\param[out] p_key_len points to an unsigned integer which will receive the length of the public RSA key . This pointer may be set to 0.
|
|
\return ::XND_ERROR_SUCCESS on success, an \ref xnodus_errors "error code" on failure, if the key contained in the object is not a public RSA key the function fails with error ::XLT_ERROR_INVALID_STATE.
|
|
\remark The unsigned integer pointed by 'p_key_len' receive the size of the key even if key_size is shorter and the function fails.
|
|
\see \ref xnd_key_data.
|
|
*/
|
|
XND_LINK int XND_API xnd_keydata_get_as_formatted_rsa_pub_key(XND_KEY_DATA key_data, OUT unsigned char* key, unsigned int key_size, unsigned int* p_key_len);
|
|
|
|
/**
|
|
\ingroup xnodus_crypto_key_man
|
|
Return the private RSA key from a key data object in PQE format (see \ref xnd_users_key).
|
|
\param[in] key_data the handle of type ::XND_KEY_DATA which points to the key data object.
|
|
\param[out] key points to a buffer that will receive the private RSA key.
|
|
\param[in] key_size the size in bytes of the buffer pointed by 'key'.
|
|
\param[out] p_key_len points to an unsigned integer which will receive the length of the private RSA key . This pointer may be set to 0.
|
|
\return ::XND_ERROR_SUCCESS on success, an \ref xnodus_errors "error code" on failure, if the key contained in the object is not a private RSA key the function fails with error ::XLT_ERROR_INVALID_STATE.
|
|
\remark The unsigned integer pointed by 'p_key_len' receive the size of the key even if key_size is shorter and the function fails.
|
|
\see \ref xnd_key_data.
|
|
*/
|
|
XND_LINK int XND_API xnd_keydata_get_as_formatted_rsa_pqe_priv_key(XND_KEY_DATA key_data, OUT unsigned char* key, unsigned int key_size, unsigned int* p_key_len);
|
|
|
|
/**
|
|
\ingroup xnodus_crypto_key_man
|
|
Return the private RSA key from a key data object in XLight format (see \ref xnd_users_key).
|
|
\param[in] key_data the handle of type ::XND_KEY_DATA which points to the key data object.
|
|
\param[out] key points to a buffer that will receive the private RSA key.
|
|
\param[in] key_size the size in bytes of the buffer pointed by 'key'.
|
|
\param[out] p_key_len points to an unsigned integer which will receive the length of the private RSA key . This pointer may be set to 0.
|
|
\return ::XND_ERROR_SUCCESS on success, an \ref xnodus_errors "error code" on failure, if the key contained in the object is not a private RSA key the function fails with error ::XLT_ERROR_INVALID_STATE.
|
|
\remark The unsigned integer pointed by 'p_key_len' receive the size of the key even if key_size is shorter and the function fails.
|
|
\see \ref xnd_key_data.
|
|
*/
|
|
XND_LINK int XND_API xnd_keydata_get_as_formatted_rsa_xlt_priv_key(XND_KEY_DATA key_data, OUT unsigned char* key, unsigned int key_size, unsigned int* p_key_len);
|
|
|
|
/**
|
|
\ingroup xnodus_crypto_key_man
|
|
Return the module length of the RSA key represented by a key data object
|
|
\param[in] key_data the handle of type ::XND_KEY_DATA which points to the key data object.
|
|
\return return the byte length of the module of the RSA key in the ::XND_KEY_DATA object. If the key is not RSA the value '0' (zero) is returned.
|
|
*/
|
|
XND_LINK int XND_API xnd_keydata_get_rsa_mod_byte_len(XND_KEY_DATA key_data);
|
|
|
|
/**
|
|
\ingroup xnodus_crypto_key_man
|
|
Return the key length of the formatted representation of the key contained int the object.
|
|
\param[in] key_data the handle of type ::XND_KEY_DATA which points to the key data object.
|
|
\return return the byte length of the formatter representation of the key in the ::XND_KEY_DATA object. On error the value '0' (zero) is returned.
|
|
*/
|
|
XND_LINK int XND_API xnd_keydata_get_key_len(XND_KEY_DATA key_data);
|
|
|
|
/**
|
|
\ingroup xnodus_crypto_key_man
|
|
Return the formatted key from a key data object.
|
|
\param[in] key_data the handle of type ::XND_KEY_DATA which points to the key data object.
|
|
\param[out] key points to a buffer that will receive the formatted key.
|
|
\param[in] key_size the size in bytes of the buffer pointed by 'key'.
|
|
\param[out] p_key_len points to an unsigned integer which will receive the length of the key . This pointer may be set to 0.
|
|
\return ::XND_ERROR_SUCCESS on success, an \ref xnodus_errors "error code" on failure.
|
|
\remark The unsigned integer pointed by 'p_key_len' receive the size of the key even if key_size is shorter and the function fails.
|
|
\see \ref xnd_key_data.
|
|
*/
|
|
XND_LINK int XND_API xnd_keydata_get_as_formatted_key(XND_KEY_DATA key_data, OUT unsigned char* key, unsigned int key_size, unsigned int* p_key_len);
|
|
|
|
/**
|
|
\ingroup xnodus_crypto_key_man
|
|
Return a string representing the key data object.
|
|
\param[in] key_data the handle of type ::XND_KEY_DATA which points to the key data object.
|
|
\param[in] wrap_key the wrap key object to be used to wrap the key. If this argument is set to '0' the returned string will be not encrypted.
|
|
\param[out] p_status points to an integer that will receive the status of the operation: ::XND_ERROR_SUCCESS on success, an \ref xnodus_errors "error code" on failure.
|
|
\return a string containing the base 64 encoding of the key data object. Use xnd_free() to free the allocated string.
|
|
\remark Free the memory pointed by the returned value using xnd_free().
|
|
\see \ref xnd_key_data.
|
|
*/
|
|
XND_LINK char* XND_API xnd_keydata_allocget_as_blob(XND_KEY_DATA key_data, OPT XND_KEY_DATA wrap_key, OPT OUT int * p_status);
|
|
|
|
////////////////////////////////////////
|
|
|
|
////////////////////////////////////////
|
|
//RSA functions
|
|
|
|
//xnd_rsa_func
|
|
|
|
/**
|
|
\ingroup xnd_rsa_func
|
|
Generate a new random private RSA key.
|
|
\param[in] env xNodus environment handle (see xnd_xlt_env_create()).
|
|
\param[in] key_bit_length length in bit of the desired RSA key.
|
|
\param[in] safe if not set to '0' compute a safe private key (it take a long time to complete).
|
|
\param[out] p_status points to an integer that will receive the status of the operation: ::XND_ERROR_SUCCESS on success, an \ref xnodus_errors "error code" on failure.
|
|
\return a ::XND_KEY_DATA handle which points to the allocated key data representing the RSA key. Use xnd_keydata_release() to release the returned object.
|
|
\see \ref xnd_key_data.
|
|
*/
|
|
XND_LINK XND_KEY_DATA XND_API xnd_keydata_rsa_generate_private_create(XND_XLT_ENV env, unsigned int key_bit_length, unsigned int safe, OPT OUT int* p_status);
|
|
|
|
|
|
|
|
|
|
|
|
//GET VALUES
|
|
//LEB = Little Endian Buffer
|
|
/**
|
|
\ingroup xnd_rsa_func
|
|
Return the modulus of an RSA key expressed as a \ref xnd_leb "little endian buffer". See \ref xnd_key_data.
|
|
\param[in] key_data the ::XND_KEY_DATA handle of a private or public RSA key.
|
|
\param[out] buffer points to the buffer that will receive the modulus value.
|
|
\param[in] buffer_size the size in bytes of the buffer pointed by the argument 'buffer'.
|
|
\param[out] p_buffer_len points to an unsigned integer that will receive the length in bytes of the modulus value.
|
|
\return ::XND_ERROR_SUCCESS on success, an \ref xnodus_errors "error code" on failure.
|
|
\note The value pointed by 'p_buffer_len' is set even if the buffer is null or the buffer size is not sufficient to receive the entire data.
|
|
*/
|
|
XND_LINK int XND_API xnd_rsa_get_modulus_leb(XND_KEY_DATA key_data, OUT unsigned char* buffer, unsigned int buffer_size, OUT unsigned int* p_buffer_len);
|
|
|
|
/**
|
|
\ingroup xnd_rsa_func
|
|
Return the public exponent of an RSA key expressed as a \ref xnd_leb "little endian buffer". See \ref xnd_key_data.
|
|
\param[in] key_data the ::XND_KEY_DATA handle of a private or public RSA key.
|
|
\param[out] buffer points to the buffer that will receive the public exponent value.
|
|
\param[in] buffer_size the size in bytes of the buffer pointed by the argument 'buffer'.
|
|
\param[out] p_buffer_len points to an unsigned integer that will receive the length in bytes of the public exponent value.
|
|
\return ::XND_ERROR_SUCCESS on success, an \ref xnodus_errors "error code" on failure.
|
|
\note The value pointed by 'p_buffer_len' is set even if the buffer is null or the buffer size is not sufficient to receive the entire data.
|
|
*/
|
|
XND_LINK int XND_API xnd_rsa_get_pub_exp_leb(XND_KEY_DATA key_data, OUT unsigned char* buffer, unsigned int buffer_size, unsigned int* p_buffer_len);
|
|
|
|
/**
|
|
\ingroup xnd_rsa_func
|
|
Return the prime number 'p' of a private RSA key expressed as a \ref xnd_leb "little endian buffer". See \ref xnd_key_data.
|
|
\param[in] key_data the ::XND_KEY_DATA handle of a private RSA key.
|
|
\param[out] buffer points to the buffer that will receive the prime number 'p' value.
|
|
\param[in] buffer_size the size in bytes of the buffer pointed by the argument 'buffer'.
|
|
\param[out] p_buffer_len points to an unsigned integer that will receive the length in bytes of the prime number 'p' value.
|
|
\return ::XND_ERROR_SUCCESS on success, an \ref xnodus_errors "error code" on failure.
|
|
\note The value pointed by 'p_buffer_len' is set even if the buffer is null or the buffer size is not sufficient to receive the entire data.
|
|
*/
|
|
XND_LINK int XND_API xnd_rsa_get_p_leb(XND_KEY_DATA key_data, OUT unsigned char* buffer, unsigned int buffer_size, unsigned int* p_buffer_len);
|
|
|
|
/**
|
|
\ingroup xnd_rsa_func
|
|
Return the prime number 'q' of a private RSA key expressed as a \ref xnd_leb "little endian buffer". See \ref xnd_key_data.
|
|
\param[in] key_data the ::XND_KEY_DATA handle of a private RSA key.
|
|
\param[out] buffer points to the buffer that will receive the prime number 'q' value.
|
|
\param[in] buffer_size the size in bytes of the buffer pointed by the argument 'buffer'.
|
|
\param[out] p_buffer_len points to an unsigned integer that will receive the length in bytes of the prime number 'q' value.
|
|
\return ::XND_ERROR_SUCCESS on success, an \ref xnodus_errors "error code" on failure.
|
|
\note The value pointed by 'p_buffer_len' is set even if the buffer is null or the buffer size is not sufficient to receive the entire data.
|
|
*/
|
|
XND_LINK int XND_API xnd_rsa_get_q_leb(XND_KEY_DATA key_data, OUT unsigned char* buffer, unsigned int buffer_size, unsigned int* p_buffer_len);
|
|
|
|
/**
|
|
\ingroup xnd_rsa_func
|
|
Return the 'dP' value (see \ref xnd_key_data) of a private RSA key expressed as a \ref xnd_leb "little endian buffer".
|
|
\param[in] key_data the ::XND_KEY_DATA handle of a private RSA key.
|
|
\param[out] buffer points to the buffer that will receive the 'dP' value.
|
|
\param[in] buffer_size the size in bytes of the buffer pointed by the argument 'buffer'.
|
|
\param[out] p_buffer_len points to an unsigned integer that will receive the length in bytes of the 'dP' value.
|
|
\return ::XND_ERROR_SUCCESS on success, an \ref xnodus_errors "error code" on failure.
|
|
\note The value pointed by 'p_buffer_len' is set even if the buffer is null or the buffer size is not sufficient to receive the entire data.
|
|
*/
|
|
XND_LINK int XND_API xnd_rsa_get_dp_leb(XND_KEY_DATA key_data, OUT unsigned char* buffer, unsigned int buffer_size, unsigned int* p_buffer_len);
|
|
|
|
/**
|
|
\ingroup xnd_rsa_func
|
|
Return the 'dQ' value (see \ref xnd_key_data) of a private RSA key expressed as a \ref xnd_leb "little endian buffer".
|
|
\param[in] key_data the ::XND_KEY_DATA handle of a private RSA key.
|
|
\param[out] buffer points to the buffer that will receive the 'dQ' value.
|
|
\param[in] buffer_size the size in bytes of the buffer pointed by the argument 'buffer'.
|
|
\param[out] p_buffer_len points to an unsigned integer that will receive the length in bytes of the 'dQ' value.
|
|
\return ::XND_ERROR_SUCCESS on success, an \ref xnodus_errors "error code" on failure.
|
|
\note The value pointed by 'p_buffer_len' is set even if the buffer is null or the buffer size is not sufficient to receive the entire data.
|
|
*/
|
|
XND_LINK int XND_API xnd_rsa_get_dq_leb(XND_KEY_DATA key_data, OUT unsigned char* buffer, unsigned int buffer_size, unsigned int* p_buffer_len);
|
|
|
|
/**
|
|
\ingroup xnd_rsa_func
|
|
Return the 'qInv' value of a private RSA key expressed as a \ref xnd_leb "little endian buffer". See \ref xnd_key_data.
|
|
|
|
'qInv' is computed as follow:
|
|
|
|
qInv = (1/q) mod p
|
|
|
|
where 'p' and 'q' are the prime numbers of the RSA key.
|
|
|
|
\param[in] key_data the ::XND_KEY_DATA handle of a private RSA key.
|
|
\param[out] buffer points to the buffer that will receive the 'qInv' value.
|
|
\param[in] buffer_size the size in bytes of the buffer pointed by the argument 'buffer'.
|
|
\param[out] p_buffer_len points to an unsigned integer that will receive the length in bytes of the 'qInv' value.
|
|
\return ::XND_ERROR_SUCCESS on success, an \ref xnodus_errors "error code" on failure.
|
|
\note The value pointed by 'p_buffer_len' is set even if the buffer is null or the buffer size is not sufficient to receive the entire data.
|
|
*/
|
|
XND_LINK int XND_API xnd_rsa_get_qinv_leb(XND_KEY_DATA key_data, OUT unsigned char* buffer, unsigned int buffer_size, unsigned int* p_buffer_len);
|
|
|
|
//CONVERT
|
|
|
|
/**
|
|
\ingroup xnd_rsa_func
|
|
Convert a \ref xnd_leb "little endian buffer" expressing a big number to its decimal string representation.
|
|
|
|
\param[in] env xNodus environment handle (see xnd_xlt_env_create()).
|
|
\param[in] num_buffer points to a buffer containing a little endian representation of a big number.
|
|
\param[in] num_buffer_len the length in bytes of the number pointed by num_buffer.
|
|
\param[out] str points to a buffer that will receive the base 10 representation string of the number.
|
|
\param[in] str_size the size of the buffer pointed by the 'str' argument.
|
|
\param[out] p_str_len points to an unsigned integer that will receive the length of the string number pointed by 'str'.
|
|
\return ::XND_ERROR_SUCCESS on success, an \ref xnodus_errors "error code" on failure.
|
|
\note The value pointed by 'p_str_len' is set even if 'num_buffer' is null or the string size is not enough to receive the entire data.
|
|
*/
|
|
XND_LINK int XND_API xnd_rsa_convert_leb_to_bignum_string(XND_XLT_ENV env, const unsigned char* num_buffer, unsigned int num_buffer_len, OUT char* str, unsigned int str_size, OPT OUT unsigned int* p_str_len);
|
|
//only positive numbers
|
|
|
|
/**
|
|
\ingroup xnd_rsa_func
|
|
Convert a decimal string representation of a positive big number to its \ref xnd_leb "little endian buffer" form.
|
|
\param[in] env xNodus environment handle (see xnd_xlt_env_create()).
|
|
\param[in] str_num points to a string containing the decimal representation of a positive big number.
|
|
\param[out] buffer points to a buffer that will receive the little endian representation of the passed big number.
|
|
\param[in] buffer_size the size in bytes of the buffer pointed by the 'buffer' argument.
|
|
\param[out] p_buffer_len points to an unsigned int that will contain the length in bytes of the little endian representation of the number.
|
|
\return ::XND_ERROR_SUCCESS on success, an \ref xnodus_errors "error code" on failure.
|
|
\note The value pointed by 'p_buffer_len' is set even if 'buffer' is null or the string size is not enough to receive the entire data.
|
|
*/
|
|
XND_LINK int XND_API xnd_rsa_convert_bignum_string_to_leb(XND_XLT_ENV env, const char* str_num, OUT unsigned char* buffer, unsigned int buffer_size, OPT OUT unsigned int* p_buffer_len);
|
|
|
|
//SET VALUES
|
|
/**
|
|
\ingroup xnd_rsa_func
|
|
Generate a ::XND_KEY_DATA object from the representation of the prime numbers and public exponenent of a private RSA key.
|
|
\param[in] env xNodus environment handle (see xnd_xlt_env_create()).
|
|
\param[in] p points to the buffer containing the \ref xnd_leb "little endian buffer" representation of the prime number 'p' of the RSA key.
|
|
\param[in] p_len the length in bytes of the representation of 'p'.
|
|
\param[in] q points to the buffer containing the \ref xnd_leb "little endian buffer" representation of the prime number 'q' of the RSA key.
|
|
\param[in] q_len the length in bytes of the representation of 'q'.
|
|
\param[in] e points to the buffer containing the \ref xnd_leb "little endian buffer" representation of the public exponenent of the RSA key.
|
|
\param[in] e_len the length in bytes of the representation of the public exponenent.
|
|
\param[out] p_status points to an integer that will receive the status of the operation: ::XND_ERROR_SUCCESS on success, an \ref xnodus_errors "error code" on failure.
|
|
\return a ::XND_KEY_DATA handle which points to the allocated key data object representing the private RSA key.
|
|
*/
|
|
XND_LINK XND_KEY_DATA XND_API xnd_keydata_rsa_priv_key_create_from_pqe_leb(XND_XLT_ENV env, const unsigned char* p, unsigned int p_len, const unsigned char* q, unsigned int q_len, const unsigned char* e, unsigned int e_len, OPT OUT int* p_status);
|
|
|
|
/**
|
|
\ingroup xnd_rsa_func
|
|
Generate a ::XND_KEY_DATA object from the representation of the modulus and public exponenent of a public RSA key.
|
|
\param[in] env xNodus environment handle (see xnd_xlt_env_create()).
|
|
\param[in] modulus points to the buffer containing the \ref xnd_leb "little endian buffer" representation of the modulus of the RSA key.
|
|
\param[in] modulus_len the length in bytes of the representation of the modulus.
|
|
\param[in] e points to the buffer containing the \ref xnd_leb "little endian buffer" representation of the public exponenent of the RSA key.
|
|
\param[in] e_len the length in bytes of the representation of the public exponenent.
|
|
\param[out] p_status points to an integer that will receive the status of the operation: ::XND_ERROR_SUCCESS on success, an \ref xnodus_errors "error code" on failure.
|
|
\return a ::XND_KEY_DATA handle which points to the allocated key data object representing the public RSA key.
|
|
*/
|
|
XND_LINK XND_KEY_DATA XND_API xnd_keydata_rsa_pub_key_create_from_me_leb(XND_XLT_ENV env, const unsigned char* modulus, unsigned int modulus_len, const unsigned char* e, unsigned int e_len, OPT OUT int* p_status);
|
|
|
|
|
|
//ENCRIPTION (RAW encryption - no OAEP and PSS applied)
|
|
/**
|
|
\ingroup xnd_rsa_func
|
|
Perform RSA encryption
|
|
\remark Use this function just for testing purpose, don't use it in your protected application.
|
|
\param[in] key_data the ::XND_KEY_DATA handle of a public or private RSA key.
|
|
\param[in] plaintext points to a buffer containing the plaintext to be encrypted.
|
|
\param[in] plaintext_len the length of the plaintext (it must be equal to the modulus length in bytes of the RSA key).
|
|
\param[out] ciphertext points to a buffer that will receive the encrypted value. The length of the ciphertext will be the same of the plaintext.
|
|
\return ::XND_ERROR_SUCCESS on success, an \ref xnodus_errors "error code" on failure.
|
|
*/
|
|
XND_LINK int XND_API xnd_rsa_raw_encrypt_leb(XND_KEY_DATA key_data, const unsigned char* plaintext, unsigned int plaintext_len, OUT unsigned char* ciphertext);
|
|
|
|
/**
|
|
\ingroup xnd_rsa_func
|
|
Perform RSA decryption
|
|
\remark Use this function just for testing purpose, don't use it in your protected application.
|
|
\param[in] key_data the ::XND_KEY_DATA handle of a private RSA key.
|
|
\param[in] ciphertext points to a buffer containing the ciphertext to be decrypted.
|
|
\param[in] ciphertext_len the length of the ciphertext (it must be equal to the modulus length in bytes of the RSA key).
|
|
\param[out] ret_plaintext points to a buffer that will receive the decrypted value. The length of the decrypted value will be the same of the ciphertext.
|
|
\return ::XND_ERROR_SUCCESS on success, an \ref xnodus_errors "error code" on failure.
|
|
*/
|
|
XND_LINK int XND_API xnd_rsa_raw_decrypt_leb(XND_KEY_DATA key_data, const unsigned char* ciphertext, unsigned int ciphertext_len, OUT unsigned char* ret_plaintext);
|
|
|
|
//calc the module respect the key
|
|
//let 'M' be the modulus of the RSA key in the __XND_KEY_DATA: this functioncompute the residue module 'M' of the little endian buffer number of ret_value
|
|
/**
|
|
\ingroup xnd_rsa_func
|
|
Compute the residue module 'm' of a number expressed in \ref xnd_leb "little endian buffer" form where 'm' is the modulus of an RSA key.
|
|
\remark Use this function just for testing purpose, don't use it in your protected application.
|
|
\param[in] key_data the ::XND_KEY_DATA handle of a private or public RSA key where the modulus is extracted.
|
|
\param[in] value points to a buffer containing the number expressed in \ref xnd_leb "little endian buffer" form from which the residue module 'm' must be computed.
|
|
\param[in] value_len length of the number representation pointed by the argument 'value'.
|
|
\param[out] ret_value points to a buffer that will receive the computed residue expressed in \ref xnd_leb "little endian buffer" form.
|
|
\param[in] ret_value_size the size in bytes of the buffer pointed by 'ret_value'.
|
|
\param[out] p_ret_value_len points to an integer that will receive the length of the returned residue value.
|
|
\return ::XND_ERROR_SUCCESS on success, an \ref xnodus_errors "error code" on failure.
|
|
*/
|
|
XND_LINK int XND_API xnd_rsa_calc_mod_key_leb(XND_KEY_DATA key_data, const unsigned char* value, unsigned int value_len, OUT unsigned char* ret_value, unsigned int ret_value_size, OPT OUT unsigned int* p_ret_value_len);
|
|
|
|
|
|
/**
|
|
\ingroup xnodus_misc
|
|
Free a buffer or a string allocated by xNodus API functions
|
|
\param[in] p points to the buffer to free.
|
|
*/
|
|
XND_LINK void XND_API xnd_free(void* p);
|
|
|
|
//\cond NOT_COMMENTED
|
|
XND_LINK unsigned char* XND_API xnd_keydata_to_bytes_alloc(XND_KEY_DATA ctx, OPT OUT unsigned int* p_len);
|
|
XND_LINK XND_KEY_DATA XND_API xnd_keydata_from_bytes_create(const unsigned char* data, unsigned int data_len);
|
|
//\endcond
|
|
|
|
/**
|
|
\ingroup xnodus_misc
|
|
Generate a pseudo random value.
|
|
\remark Use this function just for testing purpose, don't use it in your protected application.
|
|
\param[in] env xNodus environment handle (see xnd_xlt_env_create()).
|
|
\param[out] buffer points to a buffer that will receive the pseudo random value.
|
|
\param[in] buffer_len the length in bytes of the random buffer to be returned. This length cannot be greater than the size of the buffer to be filled.
|
|
\return ::XND_ERROR_SUCCESS on success, an \ref xnodus_errors "error code" on failure.
|
|
*/
|
|
XND_LINK int XND_API xnd_rand(XND_XLT_ENV env, OUT unsigned char* buffer, unsigned int buffer_len);
|
|
|
|
|
|
|
|
/**
|
|
\ingroup xnd_user_data_group
|
|
Return a pointer to a string containing the encoded form of the data related to a user (see \ref xnd_user_data).
|
|
|
|
\param[in] env xNodus environment handle (see xnd_xlt_env_create()).
|
|
\param[in] key_data the ::XND_KEY_DATA handle of an object containing a private or secret key.
|
|
\param[in] user_name points to a ::XND_USER_NAME structure containing the type and name of a user.
|
|
\param[in] wrap_key the ::XND_KEY_DATA handle of an object containing a secret key (AES) used to wrap the returned values. This argument may be set to 0 and no wrapping will be done
|
|
\param[out] p_status points to an integer that will receive the status of the operation: ::XND_ERROR_SUCCESS on success, an \ref xnodus_errors "error code" on failure.
|
|
\return return the string containing the encoded form of the data related to the user and its key.
|
|
\remark Free the memory pointed by the returned value using xnd_free().
|
|
*/
|
|
XND_LINK char* XND_API xnd_allocget_user_data(XND_XLT_ENV env, XND_KEY_DATA key_data, const XND_USER_NAME* user_name, OPT XND_KEY_DATA wrap_key, OPT OUT int* p_status);
|
|
|
|
/**
|
|
\ingroup xnd_user_data_group
|
|
Extract the user name from a user data string (see \ref xnd_user_data).
|
|
|
|
\param[in] env xNodus environment handle (see xnd_xlt_env_create()).
|
|
\param[in] user_data points to the user data string.
|
|
\param[in] wrap_key the ::XND_KEY_DATA handle of an object containing a secret key (AES) used to unwrap the user data string. If the passed string is not encrypted this entry must be set to 0.
|
|
\param[out] user_name points to a ::XND_USER_NAME structure that will contain the type and username of the user.
|
|
\return ::XND_ERROR_SUCCESS on success, an \ref xnodus_errors "error code" on failure.
|
|
\see xnd_allocget_user_data()
|
|
*/
|
|
XND_LINK int XND_API xnd_get_user_name_from_user_data_blob(XND_XLT_ENV env, const char* user_data, OPT XND_KEY_DATA wrap_key, OUT P_XND_USER_NAME user_name);
|
|
|
|
/**
|
|
\ingroup xnd_user_data_group
|
|
Create a ::XND_KEY_DATA object of the cryptographic key encoded in a user data string (see \ref xnd_user_data).
|
|
|
|
\param[in] env xNodus environment handle (see xnd_xlt_env_create()).
|
|
\param[in] user_data points to the user data string.
|
|
\param[in] wrap_key the ::XND_KEY_DATA handle of an object containing a secret key (AES) used to unwrap the user data string. If the passed string is not encrypted this entry must be set to 0.
|
|
\param[out] p_status points to an integer that will receive the status of the operation: ::XND_ERROR_SUCCESS on success, an \ref xnodus_errors "error code" on failure.
|
|
\return a ::XND_KEY_DATA handle which points to the allocated key data object representing the key contained in the user data string.
|
|
\remark Free the ::XND_KEY_DATA returned by this function with xnd_keydata_release().
|
|
*/
|
|
XND_LINK XND_KEY_DATA XND_API xnd_create_keydata_from_user_data_blob(XND_XLT_ENV env, const char* user_data, OPT XND_KEY_DATA wrap_key, OPT OUT int* p_status);
|
|
|
|
|
|
/**
|
|
\ingroup xnd_devctx_data
|
|
Create a ::XND_DEVICE_CONTEXT_DATA object (see \ref xnd_devctx_by_index).
|
|
\param[in] env xNodus environment handle (see xnd_xlt_env_create()).
|
|
\return an handle which refers to a newly created ::XND_DEVICE_CONTEXT_DATA object.
|
|
*/
|
|
XND_LINK XND_DEVICE_CONTEXT_DATA XND_API xnd_xlt_devctx_data_create(XND_XLT_ENV env);
|
|
|
|
/**
|
|
\ingroup xnd_devctx_data
|
|
Release a device context data object pointed by a ::XND_DEVICE_CONTEXT_DATA handle (see \ref xnd_create_acquire_release).
|
|
\param[in] device_context_data the ::XND_DEVICE_CONTEXT_DATA handle referencing to the object to release.
|
|
\return ::XND_ERROR_SUCCESS on success, an \ref xnodus_errors "error code" on failure, and ::XND_RELEASE_STILL_REFERENCED if there are still reference to the object.
|
|
\see \ref xnd_devctx_by_index, xnd_xlt_devctx_data_create().
|
|
*/
|
|
XND_LINK int XND_API xnd_xlt_devctx_data_release(XND_DEVICE_CONTEXT_DATA device_context_data);
|
|
|
|
/**
|
|
\ingroup xnd_devctx_data
|
|
Acquire a device context data object pointed by a ::XND_DEVICE_CONTEXT_DATA handle (see \ref xnd_create_acquire_release).
|
|
\param[in] device_context_data the ::XND_DEVICE_CONTEXT_DATA handle referencing to the object to acquire.
|
|
\return on success a reference to the input ::XND_NET_DATA handle, '0' otherwise.
|
|
\remark The reference to the ::XND_DEVICE_CONTEXT_DATA handle obtained by this function must be freed calling xnd_xlt_devctx_data_release().
|
|
\see \ref xnd_devctx_by_index, xnd_xlt_devctx_data_create().
|
|
*/
|
|
XND_LINK XND_DEVICE_CONTEXT_DATA XND_API xnd_xlt_devctx_data_acquire(XND_DEVICE_CONTEXT_DATA device_context_data);
|
|
|
|
/**
|
|
\ingroup xnd_devctx_data
|
|
Add an xNodus device context description to a ::XND_DEVICE_CONTEXT_DATA object (see \ref xnd_devctx_by_index).
|
|
\param[in] device_context_data an handle that refers to a ::XND_DEVICE_CONTEXT_DATA object to which add an xNodus device context description.
|
|
\param[in] addr_port a string representing a net address and port to be used to connect to the described xNodus device.
|
|
\param[in] xnodus_key_blob points to a string representation of the public key of the xNodus device to be contacted.
|
|
\param[in] user_data_blob points to a string encoding the user data (see \ref xnd_user_data_group). This entry may be set to 0 if an 'Anonymous' user is used (see \ref xnd_users_types).
|
|
\param[in] user_data_wrap_key_string points to a string representation of a wrap key used to unwrap the 'user_data_blob' entry. If 'user_data_blob' is set to '0' or not encrypted this entry must be set to '0'.
|
|
\param[in] keep_alive_sec establish the 'keep alive' period in seconds of the sessions that can be open on the xNodus device (see \ref xnd_keep_alive). If the value is set to '0' the default value is taken (60 seconds).
|
|
\param[in] recv_to_msec the maximum time in millisecond that the client wait for an answer from the xNodus device.
|
|
\return ::XND_ERROR_SUCCESS on success, an \ref xnodus_errors "error code" on failure.
|
|
\remark At present the entry 'addr_port' can be a string representing an IPv4 address plus a port (for example 192.168.0.123:15678) or an URL plus the port (for example xnddevice.yourdomain.com:15678).
|
|
If 'addr_port' is set to "xnodus_local_network:15678" the device will be searched in the local network, and the used port is "15678".
|
|
\see xnd_xlt_add_xnodus_to_devctx_data2(), xnd_xlt_add_xnodus_to_devctx_data3().
|
|
*/
|
|
XND_LINK int XND_API xnd_xlt_add_xnodus_to_devctx_data(XND_DEVICE_CONTEXT_DATA device_context_data, const char* addr_port, const char* xnodus_key_blob, OPT const char* user_data_blob, OPT const char* user_data_wrap_key_string, OPT unsigned int keep_alive_sec, OPT unsigned int recv_to_msec);
|
|
|
|
/**
|
|
\ingroup xnd_devctx_data
|
|
Add an xNodus device context description to a ::XND_DEVICE_CONTEXT_DATA object (see \ref xnd_devctx_by_index).
|
|
This function performs the same task of xnd_xlt_add_xnodus_to_devctx_data() with arguments passed in different formats.
|
|
\param[in] device_context_data an handle that refers to a ::XND_DEVICE_CONTEXT_DATA object to which add an xNodus device context description.
|
|
\param[in] xnd_net_data handle that refers to a ::XND_NET_DATA object containing the network connection information that must be used connecting the xNodus device.
|
|
\param[in] xnodus_key_blob points to a string representation of the public key of the xNodus device to be contacted.
|
|
\param[in] user_data_blob points to a string encoding the user data (see \ref xnd_user_data_group). This entry may be set to 0 if an 'Anonymous' user is used (see \ref xnd_users_types).
|
|
\param[in] user_data_wrap_key a handle referring to a :: XND_KEY_DATA object representing the wrap key used to unwrap the 'user_data_blob' entry. If 'user_data_blob' is set to '0' or not encrypted this entry must be set to '0'.
|
|
\param[in] keep_alive_sec establish the 'keep alive' period in seconds of the sessions that can be open on the xNodus device (see \ref xnd_keep_alive). If the value is set to '0' the default value is taken (60 seconds).
|
|
\return ::XND_ERROR_SUCCESS on success, an \ref xnodus_errors "error code" on failure.
|
|
\see xnd_xlt_add_xnodus_to_devctx_data(), xnd_xlt_add_xnodus_to_devctx_data3().
|
|
*/
|
|
XND_LINK int XND_API xnd_xlt_add_xnodus_to_devctx_data2(XND_DEVICE_CONTEXT_DATA device_context_data, XND_NET_DATA xnd_net_data, const char* xnodus_key_blob, OPT const char* user_data_blob, OPT XND_KEY_DATA user_data_wrap_key, OPT unsigned int keep_alive_sec);
|
|
|
|
/**
|
|
\ingroup xnd_devctx_data
|
|
Add an xNodus device context description to a ::XND_DEVICE_CONTEXT_DATA object (see \ref xnd_devctx_by_index).
|
|
This function performs the same task of xnd_xlt_add_xnodus_to_devctx_data() with arguments passed in different formats.
|
|
\param[in] device_context_data an handle that refers to a ::XND_DEVICE_CONTEXT_DATA object to which add an xNodus device context description.
|
|
\param[in] xnd_net_data handle that refers to a ::XND_NET_DATA object containing the network connection information that must be used connecting the xNodus device.
|
|
\param[in] xnodus_key_data handle of a ::XND_KEY_DATA object referring to the public key of the xNodus device.
|
|
\param[in] user_name points to a ::XND_USER_NAME structure containing the name of the user that will connect to the xNodus device.
|
|
\param[in] user_key_data handle of a ::XND_KEY_DATA object referring to the private (or secret) key related to the user referred by 'user_name' entry.
|
|
\param[in] keep_alive_sec establish the 'keep alive' period in seconds of the sessions that can be open on the xNodus device (see \ref xnd_keep_alive). If the value is set to '0' the default value is taken (60 seconds).
|
|
\return ::XND_ERROR_SUCCESS on success, an \ref xnodus_errors "error code" on failure.
|
|
\see xnd_xlt_add_xnodus_to_devctx_data(), xnd_xlt_add_xnodus_to_devctx_data2().
|
|
*/
|
|
XND_LINK int XND_API xnd_xlt_add_xnodus_to_devctx_data3(XND_DEVICE_CONTEXT_DATA device_context_data, XND_NET_DATA xnd_net_data, XND_KEY_DATA xnodus_key_data, OPT const XND_USER_NAME* user_name, OPT XND_KEY_DATA user_key_data, OPT unsigned int keep_alive_sec);
|
|
|
|
/**
|
|
\ingroup xnd_devctx_data
|
|
Add an xNodus device context description to a ::XND_DEVICE_CONTEXT_DATA object (see \ref xnd_devctx_by_index).
|
|
\param[in] device_context_data an handle that refers to a ::XND_DEVICE_CONTEXT_DATA object to which add an xNodus device context description.
|
|
\param[in] addr_port a string representing a net address and port to be used to connect to the described xNodus device.
|
|
\param[in] xnodus_key_blob points to a string representation of the public key of the xNodus device to be contacted.
|
|
\param[in] user_data_blob points to a string encoding the user data (see \ref xnd_user_data_group). This entry may be set to 0 if an 'Anonymous' user is used (see \ref xnd_users_types).
|
|
\param[in] user_data_wrap_key_string points to a string representation of a wrap key used to unwrap the 'user_data_blob' entry. If 'user_data_blob' is set to '0' or not encrypted this entry must be set to '0'.
|
|
\param[in] net_protocol indicates the protocol to be used. At present TCP and UDP are supported (see \ref xnd_protocol_type to specify the desired protocol). By setting this entry to zero the TCP protocol is used.
|
|
\param[in] keep_alive_sec establish the 'keep alive' period in seconds of the sessions that can be open on the xNodus device (see \ref xnd_keep_alive). If the value is set to '0' the default value is taken (60 seconds).
|
|
\param[in] recv_to_msec the maximum time in millisecond that the client wait for an answer from the xNodus device.
|
|
\return ::XND_ERROR_SUCCESS on success, an \ref xnodus_errors "error code" on failure.
|
|
\remark At present the entry 'addr_port' can be a string representing an IPv4 address plus a port (for example 192.168.0.123:15678) or an URL plus the port (for example xnddevice.yourdomain.com:15678).
|
|
If 'addr_port' is set to "xnodus_local_network:15678" the device will be searched in the local network, and the used port is "15678".
|
|
\see xnd_xlt_add_xnodus_to_devctx_data2(), xnd_xlt_add_xnodus_to_devctx_data3().
|
|
*/
|
|
XND_LINK int XND_API xnd_xlt_add_xnodus_to_devctx_data4(XND_DEVICE_CONTEXT_DATA device_context_data, const char* addr_port, const char* xnodus_key_blob, OPT const char* user_data_blob, OPT const char* user_data_wrap_key_string, OPT unsigned int net_protocol, OPT unsigned int keep_alive_sec, OPT unsigned int recv_to_msec);
|
|
|
|
|
|
/**
|
|
\ingroup xnd_devctx_data
|
|
Add an XLight connection description to a ::XND_DEVICE_CONTEXT_DATA object (see \ref xnd_devctx_by_index).
|
|
\param[in] device_context_data an handle that refers to a ::XND_DEVICE_CONTEXT_DATA object to which add an xNodus device context description.
|
|
\param[in] password the password of the XLight device (the one set by the function xnd_xlt_setup()).
|
|
\return ::XND_ERROR_SUCCESS on success, an \ref xnodus_errors "error code" on failure.
|
|
*/
|
|
XND_LINK int XND_API xnd_xlt_add_xlight_to_devctx_data(XND_DEVICE_CONTEXT_DATA device_context_data, OPT const unsigned char* password);
|
|
|
|
//\cond NOT_COMMENTED
|
|
XND_LINK unsigned char* XND_API xnd_xlt_devctx_data_to_bytes_alloc(XND_DEVICE_CONTEXT_DATA device_context_data, unsigned int* p_len);
|
|
XND_LINK XND_DEVICE_CONTEXT_DATA XND_API xnd_xlt_devctx_data_from_bytes_create(XND_XLT_ENV env, const unsigned char* data, unsigned int data_len);
|
|
//\endcond
|
|
|
|
|
|
/**
|
|
\defgroup xnd_devctx_flags Device context flags
|
|
\ingroup xnodus_defines
|
|
|
|
The bitwise 'OR' operation of a subset of the following values defines feature of the created device context
|
|
@{
|
|
*/
|
|
#define XND_XLT_DEVCTX_FLAG_XNODUS_AUTO_OPEN 0x1 ///< before sending any command to the device the session is open if not already running
|
|
#define XND_XLT_DEVCTX_FLAG_XNODUS_MANUAL_KEEP_ALIVE 0x2 ///< the keep alive (see \ref xnd_keep_alive) procedure must not be managed by the APIs
|
|
#define XND_XLT_DEVCTX_FLAG_XNODUS_AUTO_REOPEN_SESSION 0x4 ///< the APIs re-open automatically a session after a communication error (after a communication error it is very likely that client and xNodus device lose their synchronization and then lose the possibility to continue the current session)
|
|
#define XND_XLT_DEVCTX_FLAG_XNODUS_MULTI_INSTANCE 0x8 ///< multiple sessions opened by different instances of the protected application running onto a single PC consume only one license (see \ref xnd_users_group_lic).
|
|
#define XND_XLT_DEVCTX_FLAG_XLIGHT_NO_AUTO_CLOSE_SESSION 0x10 ///< On Xlight never close implicitly an open session (useful if used in multithreading). Without this setting xnd_module_devctx_release() close the session if not already done.
|
|
//@} //xnd_devctx_flags
|
|
|
|
//\ingroup xnodus_main_functions
|
|
/**
|
|
\ingroup xnd_devctx
|
|
Create an xNodus device context (see \ref xnd_device_context for an introduction on device contexts and \ref xnd_create_devctx_explicit).
|
|
\param[in] env xNodus environment handle (see xnd_xlt_env_create()).
|
|
\param[in] addr_port a pointer to the null terminated name of the host to resolve and the port expressed as \<address\>.\<port\>.
|
|
\param[in] xnodus_key_blob points to the encoding string of the xNodus RSA public key.
|
|
\param[in] user_data_blob points to the encoding string of the user data (username and private or secret key) to be used for the session open in xNodus. If this entry is set to '0' an anonymous user is used.
|
|
\param[in] user_data_wrap_key_string points to the string containing the key to unwrap 'user_data_blob'. This parameter can be set to '0' if the 'user_data_blob' argument is not encrypted (or not present).
|
|
\param[in] flags flags value obtained by the logical 'OR' of the mask values \ref xnd_devctx_flags.
|
|
\param[in] keep_alive_sec keep alive time for a session opened on this device context (see \ref xnd_keep_alive). If set to zero the default value is taken (60 seconds).
|
|
\param[in] recv_to_msec maximum time to get an answer from the connected xNodus. If set to zero the default value is taken (5 seconds).
|
|
\param[out] p_status points to an integer that will receive the status of the operation: ::XND_ERROR_SUCCESS on success, an \ref xnodus_errors "error code" on failure.
|
|
\return a ::XND_DEVICE_CONTEXT handle referring to the created device context object.
|
|
\parblock
|
|
\remark The argument 'addr_port' is a string of the form \<address\>.\<port\>, for instance: 192.168.0.125:15678 or foo.example.com:15678.
|
|
If 'addr_port' is set to "xnodus_local_network:15678" the device will be searched in the local network, and the used port is "15678".
|
|
\endparblock
|
|
\parblock
|
|
\remark The returned ::XND_DEVICE_CONTEXT handle must be released calling xnd_xlt_devctx_release().
|
|
\endparblock
|
|
\see xnd_xlt_devctx_xnodus_create2(), xnd_xlt_devctx_xnodus_create3().
|
|
*/
|
|
XND_LINK XND_DEVICE_CONTEXT XND_API xnd_xlt_devctx_xnodus_create(XND_XLT_ENV env, const char* addr_port, const char* xnodus_key_blob, OPT const char* user_data_blob, OPT const char* user_data_wrap_key_string, OPT unsigned int flags, OPT unsigned int keep_alive_sec, OPT unsigned int recv_to_msec, OPT OUT int* p_status);
|
|
|
|
/**
|
|
\ingroup xnd_devctx
|
|
Create an xNodus device context (see \ref xnd_device_context for an introduction on device contexts and \ref xnd_create_devctx_explicit).
|
|
|
|
This function is similar to xnd_xlt_devctx_xnodus_create() and only differs for the different argumet type passed.
|
|
\param[in] env xNodus environment handle (see xnd_xlt_env_create()).
|
|
\param[in] xnd_net_data a ::XND_NET_DATA handle referring to the phisical address of the xNodus device.
|
|
\param[in] xnodus_key_blob points to the encoding string of the xNodus RSA public key.
|
|
\param[in] user_data_blob points to the encoding string of the user data (username and private or secret key) to be used for the session open in xNodus. If this entry is set to '0' an anonymous user is used.
|
|
\param[in] user_data_wrap_key a handle referring to a :: XND_KEY_DATA object representing the wrap key used to unwrap the 'user_data_blob' entry. If 'user_data_blob' is set to '0' or not encrypted this entry must be set to '0'.
|
|
\param[in] flags flags value obtained by the logical 'OR' of the mask values \ref xnd_devctx_flags.
|
|
\param[in] keep_alive_sec keep alive time for a session opened on this device context (see \ref xnd_keep_alive). If set to zero the default value is taken (60 seconds).
|
|
\param[out] p_status points to an integer that will receive the status of the operation: ::XND_ERROR_SUCCESS on success, an \ref xnodus_errors "error code" on failure.
|
|
\return a ::XND_DEVICE_CONTEXT handle referring to the created device context object.
|
|
\parblock
|
|
\remark The returned ::XND_DEVICE_CONTEXT handle must be released calling xnd_xlt_devctx_release().
|
|
\endparblock
|
|
\see xnd_xlt_devctx_xnodus_create(), xnd_xlt_devctx_xnodus_create3().
|
|
*/
|
|
XND_LINK XND_DEVICE_CONTEXT XND_API xnd_xlt_devctx_xnodus_create2(XND_XLT_ENV env, XND_NET_DATA xnd_net_data, const char* xnodus_key_blob, OPT const char* user_data_blob, OPT XND_KEY_DATA user_data_wrap_key, OPT unsigned int flags, OPT unsigned int keep_alive_sec, OPT OUT int* p_status);
|
|
|
|
/**
|
|
\ingroup xnd_devctx
|
|
Create an xNodus device context (see \ref xnd_device_context for an introduction on device contexts and \ref xnd_create_devctx_explicit).
|
|
|
|
This function is similar to xnd_xlt_devctx_xnodus_create() and only differs for the different argumet type passed.
|
|
\param[in] env xNodus environment handle (see xnd_xlt_env_create()).
|
|
\param[in] xnd_net_data a ::XND_NET_DATA handle referring to the phisical address of the xNodus device.
|
|
\param[in] xnodus_key_data handle of a ::XND_KEY_DATA object referring to the public key of the xNodus device.
|
|
\param[in] user_name points to a ::XND_USER_NAME structure containing the name of the user that will connect to the xNodus device. If this entry is set to '0' an anonymous user is used.
|
|
\param[in] user_key_data handle of a ::XND_KEY_DATA object referring to the private (or secret) key related to the user referred by 'user_name' entry. If 'user_name' refers to an anonymous user this entry must be set to '0'.
|
|
\param[in] flags flags value obtained by the logical 'OR' of the mask values \ref xnd_devctx_flags.
|
|
\param[in] keep_alive_sec keep alive time for a session opened on this device context (see \ref xnd_keep_alive). If set to zero the default value is taken (60 seconds).
|
|
\param[out] p_status points to an integer that will receive the status of the operation: ::XND_ERROR_SUCCESS on success, an \ref xnodus_errors "error code" on failure.
|
|
\return a ::XND_DEVICE_CONTEXT handle referring to the created device context object.
|
|
\parblock
|
|
\remark The returned ::XND_DEVICE_CONTEXT handle must be released calling xnd_xlt_devctx_release().
|
|
\endparblock
|
|
\see xnd_xlt_devctx_xnodus_create(), xnd_xlt_devctx_xnodus_create2().
|
|
*/
|
|
XND_LINK XND_DEVICE_CONTEXT XND_API xnd_xlt_devctx_xnodus_create3(XND_XLT_ENV env, XND_NET_DATA xnd_net_data, XND_KEY_DATA xnodus_key_data, OPT const XND_USER_NAME* user_name, OPT XND_KEY_DATA user_key_data, OPT unsigned int flags, OPT unsigned int keep_alive_sec, OPT OUT int* p_status);
|
|
|
|
/**
|
|
\ingroup xnd_devctx
|
|
Create an xNodus device context (see \ref xnd_device_context for an introduction on device contexts and \ref xnd_create_devctx_explicit).
|
|
\param[in] env xNodus environment handle (see xnd_xlt_env_create()).
|
|
\param[in] addr_port a pointer to the null terminated name of the host to resolve and the port expressed as \<address\>.\<port\>.
|
|
\param[in] xnodus_key_blob points to the encoding string of the xNodus RSA public key.
|
|
\param[in] user_data_blob points to the encoding string of the user data (username and private or secret key) to be used for the session open in xNodus. If this entry is set to '0' an anonymous user is used.
|
|
\param[in] user_data_wrap_key_string points to the string containing the key to unwrap 'user_data_blob'. This parameter can be set to '0' if the 'user_data_blob' argument is not encrypted (or not present).
|
|
\param[in] flags flags value obtained by the logical 'OR' of the mask values \ref xnd_devctx_flags.
|
|
\param[in] net_protocol indicates the protocol to be used. At present TCP and UDP are supported (see \ref xnd_protocol_type to specify the desired protocol). By setting this entry to zero the TCP protocol is used.
|
|
\param[in] keep_alive_sec keep alive time for a session opened on this device context (see \ref xnd_keep_alive). If set to zero the default value is taken (60 seconds).
|
|
\param[in] recv_to_msec maximum time to get an answer from the connected xNodus. If set to zero the default value is taken (5 seconds).
|
|
\param[out] p_status points to an integer that will receive the status of the operation: ::XND_ERROR_SUCCESS on success, an \ref xnodus_errors "error code" on failure.
|
|
\return a ::XND_DEVICE_CONTEXT handle referring to the created device context object.
|
|
\parblock
|
|
\remark The argument 'addr_port' is a string of the form \<address\>.\<port\>, for instance: 192.168.0.125:15678 or foo.example.com:15678.
|
|
If 'addr_port' is set to "xnodus_local_network:15678" the device will be searched in the local network, and the used port is "15678".
|
|
\endparblock
|
|
\parblock
|
|
\remark The returned ::XND_DEVICE_CONTEXT handle must be released calling xnd_xlt_devctx_release().
|
|
\endparblock
|
|
\see xnd_xlt_devctx_xnodus_create2(), xnd_xlt_devctx_xnodus_create3().
|
|
*/
|
|
XND_LINK XND_DEVICE_CONTEXT XND_API xnd_xlt_devctx_xnodus_create4(XND_XLT_ENV env, const char* addr_port, const char* xnodus_key_blob, OPT const char* user_data_blob, OPT const char* user_data_wrap_key_string, OPT unsigned int flags, OPT unsigned int net_protocol, OPT unsigned int keep_alive_sec, OPT unsigned int recv_to_msec, OPT OUT int* p_status);
|
|
|
|
//\ingroup xnodus_main_functions
|
|
/**
|
|
\ingroup xnd_devctx
|
|
Create an XLight device context (see \ref xnd_device_context for an introduction on device contexts).
|
|
|
|
This function is analogous to xnd_xlt_devctx_xnodus_create() but here the device context refer to an XLight device rather then xNodus.
|
|
\param[in] env xNodus environment handle (see xnd_xlt_env_create()).
|
|
\param[in] device device index for the selection of a specific XLight device. This value runs from 0 to ::XLT_DEVICE_MAX -1.
|
|
\param[in] password points to a buffer of length ::XLT_PASSWORD_SIZE. It contains the password to be assigned to the device. This entry may be set to '0'.
|
|
\param[in] flags flags value obtained by the logical 'OR' of the mask values \ref xnd_devctx_flags.
|
|
\param[out] p_status points to an integer that will receive the status of the operation: ::XND_ERROR_SUCCESS on success, an \ref xnodus_errors "error code" on failure.
|
|
\return a ::XND_DEVICE_CONTEXT handle referring to the created device context object.
|
|
\remark The returned ::XND_DEVICE_CONTEXT handle must be released calling xnd_xlt_devctx_release().
|
|
*/
|
|
XND_LINK XND_DEVICE_CONTEXT XND_API xnd_xlt_devctx_xlight_create(XND_XLT_ENV env, unsigned int device, OPT const unsigned char* password, OPT unsigned int flags, OPT OUT int* p_status);
|
|
|
|
#define XNODUS_DEVICE_BASE_INDEX XLT_DEVICE_MAX ///< starting device address for xNodus device when using xnd_xlt_devctx_create(). Lower device values refer to XLight
|
|
|
|
/**
|
|
\ingroup xnd_devctx
|
|
Create an xNodus or XLight device context (see \ref xnd_device_context for an introduction on device contexts and \ref xnd_devctx_by_index).
|
|
\param[in] device_context_data handle of an object of type ::XND_DEVICE_CONTEXT_DATA collecting the set of xNodus and XLight description of managed devices.
|
|
\param[in] device the index of the device on which create the device context.
|
|
\param[in] flags flags value obtained by the logical 'OR' of the mask values \ref xnd_devctx_flags.
|
|
\param[out] p_status points to an integer that will receive the status of the operation: ::XND_ERROR_SUCCESS on success, an \ref xnodus_errors "error code" on failure.
|
|
\return a ::XND_DEVICE_CONTEXT handle referring to the created device context object.
|
|
\remark if the argument 'device' runs from 0 to ::XLT_DEVICE_MAX -1 an XLight is instance is created, while for values equal or greater than ::XLT_DEVICE_MAX
|
|
an xNodus instance is created.
|
|
*/
|
|
XND_LINK XND_DEVICE_CONTEXT XND_API xnd_xlt_devctx_create(XND_DEVICE_CONTEXT_DATA device_context_data, unsigned int device, OPT unsigned int flags, OPT OUT int* p_status);
|
|
|
|
//\ingroup xnodus_main_functions
|
|
/**
|
|
\ingroup xnd_devctx
|
|
Release a device context object pointed by a ::XND_DEVICE_CONTEXT handle (see \ref xnd_create_acquire_release).
|
|
\param[in] dev_ctx the ::XND_DEVICE_CONTEXT handle referencing to the object to release.
|
|
\return ::XND_ERROR_SUCCESS on success, an \ref xnodus_errors "error code" on failure, and ::XND_RELEASE_STILL_REFERENCED if there are still reference to the object.
|
|
*/
|
|
XND_LINK int XND_API xnd_xlt_devctx_release(XND_DEVICE_CONTEXT dev_ctx);
|
|
|
|
/**
|
|
\ingroup xnd_devctx
|
|
Acquire a device context object pointed by a ::XND_DEVICE_CONTEXT handle (see \ref xnd_create_acquire_release).
|
|
\param[in] dev_ctx a ::XND_DEVICE_CONTEXT handle referencing the object to acquire.
|
|
\return on success a reference to the input ::XND_DEVICE_CONTEXT handle, '0' otherwise.
|
|
\remark The reference to the ::XND_DEVICE_CONTEXT handle obtained by this function must be freed calling xnd_xlt_devctx_release().
|
|
*/
|
|
XND_LINK XND_DEVICE_CONTEXT XND_API xnd_xlt_devctx_acquire(XND_DEVICE_CONTEXT dev_ctx);
|
|
|
|
/**
|
|
\ingroup xnd_devctx
|
|
Return the device index of the device context.
|
|
\param[in] dev_ctx a ::XND_DEVICE_CONTEXT handle referring to the device context object.
|
|
\return return the index value of the device context.
|
|
\remark If the device context was created on an XLight dongle the returned value runs from 0 to ::XLT_DEVICE_MAX - 1, if the device context was created using xnd_xlt_devctx_create() on an xNodus device
|
|
the returned value is a value equal or grater than ::XLT_DEVICE_MAX, and finally if the device context was created with xnd_xlt_devctx_xnodus_create(), xnd_xlt_devctx_xnodus_create2() or xnd_xlt_devctx_xnodus_create3() the
|
|
returned value is always ::XLT_DEVICE_MAX.
|
|
*/
|
|
XND_LINK unsigned int XND_API xnd_xlt_devctx_get_device_index(XND_DEVICE_CONTEXT dev_ctx);
|
|
|
|
//\ingroup xnodus_main_functions
|
|
/**
|
|
\ingroup xnd_session
|
|
Open the session of a device context (See \ref xnd_session).
|
|
\param[in] dev_ctx a ::XND_DEVICE_CONTEXT handle referring to the device context object.
|
|
\param[in] wrap_key_or_password points to a buffer of length 32 bytes containing an XLight password or a wrap key for an xNodus user data string(see \ref xnd_deferring_wrap_key).
|
|
\return ::XND_ERROR_SUCCESS on success, an \ref xnodus_errors "error code" on failure.
|
|
\see xnd_xlt_session_open2(), xnd_xlt_session_open3()
|
|
*/
|
|
XND_LINK int XND_API xnd_xlt_session_open(XND_DEVICE_CONTEXT dev_ctx, OPT const unsigned char* wrap_key_or_password);
|
|
|
|
/**
|
|
\ingroup xnd_session
|
|
Open the session of a device context (See \ref xnd_session).
|
|
\param[in] dev_ctx a ::XND_DEVICE_CONTEXT handle referring to the device context object.
|
|
\param[in] wrap_key_string points to an xNodus wrap key string of an xNodus user data blob string (see \ref xnd_deferring_wrap_key).
|
|
\return ::XND_ERROR_SUCCESS on success, an \ref xnodus_errors "error code" on failure.
|
|
\remark With this function it is not possible to open a device context on an XLight device unless the 'wrap_key_string' entry is set to zero.
|
|
\see xnd_xlt_session_open(), xnd_xlt_session_open3()
|
|
*/
|
|
XND_LINK int XND_API xnd_xlt_session_open2(XND_DEVICE_CONTEXT dev_ctx, OPT const char* wrap_key_string);
|
|
|
|
/**
|
|
\ingroup xnd_session
|
|
Open the session of a device context (See \ref xnd_session).
|
|
\param[in] dev_ctx a ::XND_DEVICE_CONTEXT handle referring to the device context object.
|
|
\param[in] wrap_key handle of a ::XND_KEY_DATA object referring to the wrap key of an xNodus user data blob string (see \ref xnd_deferring_wrap_key).
|
|
\return ::XND_ERROR_SUCCESS on success, an \ref xnodus_errors "error code" on failure.
|
|
\remark With this function it is not possible to open a device context on an XLight device unless the 'wrap_key' entry is set to zero.
|
|
\see xnd_xlt_session_open(), xnd_xlt_session_open2()
|
|
*/
|
|
XND_LINK int XND_API xnd_xlt_session_open3(XND_DEVICE_CONTEXT dev_ctx, OPT XND_KEY_DATA wrap_key);
|
|
|
|
//\ingroup xnodus_main_functions
|
|
/**
|
|
\ingroup xnd_session
|
|
Close the session of a device context (See \ref xnd_session).
|
|
\param[in] dev_ctx a ::XND_DEVICE_CONTEXT handle referring to the device context object.
|
|
\return ::XND_ERROR_SUCCESS on success, an \ref xnodus_errors "error code" on failure.
|
|
*/
|
|
XND_LINK int XND_API xnd_xlt_session_close(XND_DEVICE_CONTEXT dev_ctx);
|
|
|
|
/**
|
|
\ingroup xnd_session
|
|
Send a manual keep alive command to the device (see \ref xnd_keep_alive).
|
|
\param[in] dev_ctx a ::XND_DEVICE_CONTEXT handle referring to the device context object.
|
|
\return ::XND_ERROR_SUCCESS on success, an \ref xnodus_errors "error code" on failure.
|
|
\remark This function must be called only when the session is open.
|
|
*/
|
|
XND_LINK int XND_API xnd_xlt_session_keep_alive(XND_DEVICE_CONTEXT dev_ctx);
|
|
|
|
//////////////////////////////////////////
|
|
//device context types
|
|
/**
|
|
\defgroup xnd_devctx_type Device context Type
|
|
\ingroup xnodus_defines
|
|
These are the possible device context type values. These value are related to the hardware of the connected device that can be an xNodus or an XLight.
|
|
@{
|
|
*/
|
|
#define XND_DEVICE_CONTEXT_TYPE_UNKNOWN 0 ///< unknown device
|
|
#define XND_DEVICE_CONTEXT_TYPE_XLIGHT 1 ///< XLight device attached
|
|
#define XND_DEVICE_CONTEXT_TYPE_XNODUS 2 ///< xNodus device attached
|
|
//@} //xnd_devctx_type
|
|
|
|
/**
|
|
\ingroup xnd_devctx
|
|
Return the type of the device related to the current device context
|
|
\param dev_ctx the device context handle
|
|
\return a value from \ref xnd_devctx_type.
|
|
*/
|
|
XND_LINK unsigned int XND_API xnd_xlt_get_devctx_type(XND_DEVICE_CONTEXT dev_ctx);
|
|
|
|
/**
|
|
\ingroup xnd_session
|
|
Check whether a device context is in open session state or not
|
|
\param[in] dev_ctx a ::XND_DEVICE_CONTEXT handle referring to the device context object.
|
|
\return non zero if the device context is open, return 0 if not open or an error occurred.
|
|
*/
|
|
XND_LINK int XND_API xnd_xlt_is_session_open(XND_DEVICE_CONTEXT dev_ctx);
|
|
|
|
|
|
//xnodus_modules
|
|
/**
|
|
\ingroup xnodus_modules
|
|
Create a device context referring a given module (see \ref xnd_modules).
|
|
\param[in] dev_ctx a ::XND_DEVICE_CONTEXT handle referring to the device context object.
|
|
\param[in] module_index the index of the module to be opened. This value must be equal or grater than '0' and less than ::XND_MAX_NUM_MODULES.
|
|
\param[out] p_status points to an integer that will receive the status of the operation: ::XND_ERROR_SUCCESS on success, an \ref xnodus_errors "error code" on failure.
|
|
\return a ::XND_DEVICE_CONTEXT handle referring to the newly created device context object.
|
|
\remark When calling this function the device context referred by the 'dev_ctx' argument must be in open session state.
|
|
|
|
\remark The object allocated by this function can be acquired with xnd_xlt_devctx_acquire() and must be freed calling xnd_module_devctx_release() or xnd_xlt_devctx_release();
|
|
\remark This feature is supported also on XLight version 2.50 and later. On XLight it is not necessary to open the session to call this function.
|
|
*/
|
|
XND_LINK XND_DEVICE_CONTEXT XND_API xnd_module_devctx_create(XND_DEVICE_CONTEXT dev_ctx, unsigned int module_index, OPT OUT int* p_status);
|
|
|
|
/**
|
|
\ingroup xnodus_modules
|
|
Release a device context context object pointed by a ::XND_DEVICE_CONTEXT handle created with xnd_module_devctx_create() (see \ref xnd_create_acquire_release), and release the module usage too.
|
|
\param[in] dev_ctx the ::XND_DEVICE_CONTEXT handle referencing to the object to release.
|
|
\return ::XND_ERROR_SUCCESS on success, an \ref xnodus_errors "error code" on failure, and ::XND_RELEASE_STILL_REFERENCED if there are still reference to the object.
|
|
*/
|
|
XND_LINK int XND_API xnd_module_devctx_release(XND_DEVICE_CONTEXT dev_ctx);
|
|
|
|
/**
|
|
\ingroup xnodus_modules
|
|
Return the module index of a device context.
|
|
\param[in] dev_ctx a ::XND_DEVICE_CONTEXT handle referring to the device context object.
|
|
\return return the module index of the device context. If no module is open on the device context or an error occurred the returned value is 0xFFFFFFFF.
|
|
*/
|
|
XND_LINK unsigned int XND_API xnd_module_get_index(XND_DEVICE_CONTEXT dev_ctx);
|
|
|
|
/** \defgroup xnodus_module_challenge_defs Module challenge constants
|
|
\ingroup xnodus_defines
|
|
Maximum lengths related to the used cryptographic key of the challenge argument passed to the function xnd_xlt_module_challenge()
|
|
@{
|
|
*/
|
|
#define XND_XLT_MODULE_CHALLENGE_RSA2048_MAX_LEN 254 ///< maximum length of the challenge argument of xnd_xlt_module_challenge() when RSA 2048 is used
|
|
#define XND_XLT_MODULE_CHALLENGE_RSA1024_MAX_LEN 126 ///< maximum length of the challenge argument of xnd_xlt_module_challenge() when RSA 1024 is used
|
|
#define XND_XLT_MODULE_CHALLENGE_RSA512_MAX_LEN 62 ///< maximum length of the challenge argument of xnd_xlt_module_challenge() when RSA 512 is used
|
|
#define XND_XLT_MODULE_CHALLENGE_AES_MAX_LEN 15 ///< maximum length of the challenge argument of xnd_xlt_module_challenge() when AES is used
|
|
// @}
|
|
|
|
/**
|
|
\ingroup xnodus_modules
|
|
Run the module challenge function for testing if a given module is used or not (see \ref xnd_module_challenge).
|
|
\param[in] dev_ctx a ::XND_DEVICE_CONTEXT handle referring to a device context object with open session.
|
|
\param[in] key_type key type of the used key. This value takes values from \ref xnd_info_key_type.
|
|
\param[in] challenge points to a random buffer to be used for the module challenge and verification.
|
|
\param[in] challenge_len the length of the challange buffer. The length must be less than 16 if AES is used, If the key_type refers to a RSA key challenge_len must not exceed the length in bytes of the modulus minus two (see \ref xnodus_module_challenge_defs).
|
|
\param[in] module the module index to be queried (takes value from 0 to ::XND_MAX_NUM_MODULES -1 included).
|
|
\param[out] verify_buffer points to a buffer that will receive the value computed by xNodus or XLight.
|
|
\param[in] verify_buffer_size the size in bytes of verify_buffer.
|
|
\param[out] p_verify_buffer_len points to an unsigned integer that will receive the real length of verify_buffer.
|
|
\return ::XND_ERROR_SUCCESS on success, an \ref xnodus_errors "error code" on failure.
|
|
\remark This feature is supported also on XLight version 2.50 and later. On XLight it is not necessary to open the session to call this function.
|
|
|
|
\remark The key_type entry identify the key to be used by the function. The addressed keys are the non volatile keys (see \ref xnd_non_volatile, xnd_non_volatile_key_set()).
|
|
On XLight the addressed key are set by the functions xnd_xlt_set_modules_key_cmd_wrap() and xnd_xlt_set_modules_key_apply().
|
|
\see xnd_xlt_never_use_module_verify()
|
|
*/
|
|
XND_LINK int XND_API xnd_xlt_module_challenge(XND_DEVICE_CONTEXT dev_ctx, unsigned int key_type, const unsigned char* challenge, unsigned int challenge_len, unsigned int module, unsigned char* verify_buffer, unsigned int verify_buffer_size, unsigned int* p_verify_buffer_len);
|
|
|
|
/**
|
|
\ingroup xnodus_modules
|
|
Run the module verify function for testing if a given module is open or not (see \ref xnd_module_challenge).
|
|
\remark This function must be used only for testing purpose, don't use it in your release protected application. Write on your own the verification process.
|
|
|
|
\param[in] dev_ctx a generic device context handle.
|
|
\param[in] key_type key type of used key. This value takes values from \ref xnd_info_key_type.
|
|
\param[in] key points to a buffer containing a key expressed in XLight or xNodus format (see \ref xnd_key_data).
|
|
\param[in] key_len the length of the key entry.
|
|
\param[in] challenge points to a buffer containing the same challange value used by xnd_xlt_module_challenge().
|
|
\param[in] challenge_len the length of the challange buffer.
|
|
\param[in] module the module index as set in xnd_xlt_module_challenge().
|
|
\param[in] verify_buffer points to the buffer returned by xnd_xlt_module_challenge().
|
|
\param[in] verify_buffer_len the length of the verify_buffer entry.
|
|
\return ::XND_ERROR_SUCCESS on success, if the challenge-verification procedure fails it returns ::XND_ERROR_INVALID_ARGUMENT meaning the 'verify_buffer' doesn't represent a right buffer certificating the module as open.
|
|
|
|
\see xnd_xlt_module_challenge()
|
|
*/
|
|
XND_LINK int XND_API xnd_xlt_never_use_module_verify(XND_DEVICE_CONTEXT dev_ctx, unsigned int key_type, const unsigned char* key, unsigned int key_len,
|
|
const unsigned char* challenge, unsigned int challenge_len, unsigned int module, const unsigned char* verify_buffer, unsigned int verify_buffer_len);
|
|
//xnodus_modules
|
|
|
|
///////////////////////////////////////////////////////////////////////////////////////////////////////////////////////
|
|
|
|
/**
|
|
\ingroup xnd_functions
|
|
Return information on the connected xNodus device
|
|
\param[in] dev_ctx a ::XND_DEVICE_CONTEXT handle referring to the device context object.
|
|
\param[out] p_xnd_info points to a ::XND_INFO structure that will receive the information from the xNodus device.
|
|
\return ::XND_ERROR_SUCCESS on success, an \ref xnodus_errors "error code" on failure.
|
|
*/
|
|
XND_LINK int XND_API xnd_get_info(XND_DEVICE_CONTEXT dev_ctx, OUT P_XND_INFO p_xnd_info);
|
|
|
|
|
|
//admin_key_type is as in ::XND_INFO and ::XND_USER_INFO
|
|
|
|
/**
|
|
\ingroup xnd_functions
|
|
Initialize a non initialized xNodus device.
|
|
\param[in] dev_ctx a ::XND_DEVICE_CONTEXT handle referring to a device context object with open session.
|
|
\param[in] label points to a 64 bytes buffer containing the label to be set on the xNodus device.
|
|
\param[in] service_key points to a 32 bytes buffer containing a key that will be used for cryptographic operation on xNodus. This value must be kept secret and never used inside the protected program.
|
|
\param[in] admin_key_type key type of the administrator key. This value takes values from \ref xnd_info_key_type.
|
|
\param[in] admin_key points to the buffer containing the adminstrator public key. It must be a formatted RSA public key (see \ref xnd_key_data)
|
|
\param[in] admin_key_len the length in bytes of the adminstrator key.
|
|
\param[in] xnodus_key_type key type of the xNodus public key. This value takes values from \ref xnd_info_key_type.
|
|
\param[in] xnodus_key points to the buffer containing the xNodus private RSA key. It must be a PQE formatted key or XLight style RSA private key (see \ref xnd_key_data)
|
|
\param[in] xnodus_key_len the length in bytes of the xNodus public key.
|
|
\return ::XND_ERROR_SUCCESS on success, an \ref xnodus_errors "error code" on failure.
|
|
\remark This function can be called only once, unless xnd_virginize() is called.
|
|
|
|
\remark Note that 'admin_key' is a public RSA key, while 'xnodus_key' is a private RSA key. If both entries are set to 0, the device is initialized with the default values (that is the keys set during production by OxySec).
|
|
|
|
\remark This function can be called only from an open session of the adminstrator user (see \ref xnd_users_types).
|
|
*/
|
|
XND_LINK int XND_API xnd_init_device(XND_DEVICE_CONTEXT dev_ctx, const unsigned char* label, const unsigned char* service_key,
|
|
unsigned int admin_key_type, const unsigned char* admin_key, unsigned int admin_key_len, unsigned int xnodus_key_type, const unsigned char* xnodus_key, unsigned int xnodus_key_len);
|
|
|
|
/**
|
|
\ingroup xnd_functions
|
|
Virginize an xNodus device.
|
|
|
|
This function restores an xNodus device to its initial state. It deletes users if present, it deletes the xNodus label and the 'service_key' set by xnd_init_device(),
|
|
and restore the xNodus and adminstrator key to the default values from OxySec. The only unchanged values are the net settings and the licenses of the device. After calling this function it can be called xnd_init_device().
|
|
\remark Never call this function on field.
|
|
\param[in] dev_ctx a ::XND_DEVICE_CONTEXT handle referring to a device context object with open session.
|
|
\return ::XND_ERROR_SUCCESS on success, an \ref xnodus_errors "error code" on failure.
|
|
\remark This function can be called only from an open session of the adminstrator user (see \ref xnd_users_types).
|
|
*/
|
|
XND_LINK int XND_API xnd_virginize(XND_DEVICE_CONTEXT dev_ctx);
|
|
|
|
/**
|
|
\ingroup xnd_functions
|
|
Set the network parameter of an xNodus device.
|
|
\param[in] dev_ctx a ::XND_DEVICE_CONTEXT handle referring to a device context object with open session.
|
|
\param[in] net_param points to a ::XND_NET_PARAM structure.
|
|
\return ::XND_ERROR_SUCCESS on success, an \ref xnodus_errors "error code" on failure.
|
|
*/
|
|
XND_LINK int XND_API xnd_set_network_param(XND_DEVICE_CONTEXT dev_ctx, const XND_NET_PARAM* net_param);
|
|
|
|
/**
|
|
\ingroup xnd_functions
|
|
Set the information that must visible using the xnd_get_info() function.
|
|
\param[in] dev_ctx a ::XND_DEVICE_CONTEXT handle referring to a device context object with open session.
|
|
\param[in] out_mask bitwise OR of the values from \ref xnd_significant_flag defining which data can be returned by xnd_get_info() when called outside a session.
|
|
\param[in] in_mask bitwise OR of the values from \ref xnd_significant_flag defining which data can be returned by xnd_get_info() when called inside a session by the 'Anonymous' and normal users (see \ref xnd_users_types).
|
|
\return ::XND_ERROR_SUCCESS on success, an \ref xnodus_errors "error code" on failure.
|
|
\remark This function can be called only from an open session of the adminstrator user (see \ref xnd_users_types).
|
|
*/
|
|
XND_LINK int XND_API xnd_set_visible_info(XND_DEVICE_CONTEXT dev_ctx, unsigned int out_mask, unsigned int in_mask);
|
|
|
|
|
|
/**
|
|
\ingroup xnd_list_username
|
|
Create a ::XND_USER_FIND object to start a normal user (see \ref xnd_users_types) enumeration on an xNodus device.
|
|
\param[in] dev_ctx a ::XND_DEVICE_CONTEXT handle referring to a device context object with open session.
|
|
\return an handle of a ::XND_USER_FIND object.
|
|
\remark The value returned by this function must be always freed calling xnd_get_user_list_finalize().
|
|
|
|
\see xnd_get_user_list_next(), xnd_get_user_list_finalize().
|
|
*/
|
|
XND_LINK XND_USER_FIND XND_API xnd_get_user_list_start(XND_DEVICE_CONTEXT dev_ctx);
|
|
|
|
//\cond NOT_COMMENTED
|
|
//XND_LINK int XND_API xnd_get_user_list_start(XND_DEVICE_CONTEXT dev_ctx, void* dev_ctx);
|
|
XND_LINK int XND_API xnd_reserved1(XND_DEVICE_CONTEXT dev_ctx, void* xnd_user_find);
|
|
//\endcond
|
|
|
|
/**
|
|
\ingroup xnd_list_username
|
|
Return the next username of the list of normal users (see \ref xnd_users_types) present on an xNodus device.
|
|
\param[in] xnd_find an handle of type ::XND_USER_FIND returned by xnd_get_user_list_start().
|
|
\param[out] user_name points to a structure of type ::XND_USER_NAME that will contain the next username found.
|
|
\return ::XND_ERROR_SUCCESS on success, return XND_ERROR_DEV_USER_NO_MORE_USER_AVAILABLE when no more users are present, an \ref xnodus_errors "error code" on failure.
|
|
\remark The 'Anonymous' and 'Administrator' users (see \ref xnd_users_types) are not listed.
|
|
|
|
\see xnd_get_user_list_start(), xnd_get_user_list_finalize().
|
|
*/
|
|
XND_LINK int XND_API xnd_get_user_list_next(XND_USER_FIND xnd_find, OUT P_XND_USER_NAME user_name);
|
|
//\cond NOT_COMMENTED
|
|
XND_LINK int XND_API xnd_reserved2(void* xnd_find, XND_DEVICE_CONTEXT dev_ctx, OUT P_XND_USER_NAME user_name);
|
|
//\endcond
|
|
|
|
/**
|
|
\ingroup xnd_list_username
|
|
Finalize an xNodus username search.
|
|
\param[in] xnd_find an handle of type ::XND_USER_FIND returned by xnd_get_user_list_start().
|
|
\return ::XND_ERROR_SUCCESS on success, an \ref xnodus_errors "error code" on failure.
|
|
\remark This function can be called also before the search has been completed.
|
|
|
|
\remark This function can be called only from an administrator session.
|
|
\see xnd_get_user_list_start(), xnd_get_user_list_next().
|
|
*/
|
|
XND_LINK int XND_API xnd_get_user_list_finalize(XND_USER_FIND xnd_find);
|
|
|
|
/**
|
|
\ingroup xnd_list_username_idx
|
|
Create a ::XND_USER_FIND_IDX object to start a normal user (see \ref xnd_users_types) enumeration on an xNodus device returning also the internal index value of each user.
|
|
\param[in] dev_ctx a ::XND_DEVICE_CONTEXT handle referring to a device context object with open session.
|
|
\return an handle of a ::XND_USER_FIND_IDX object.
|
|
\remark The value returned by this function must be always freed calling xnd_get_user_list_idx_finalize().
|
|
|
|
\see xnd_get_user_list_idx_next(), xnd_get_user_list_idx_finalize().
|
|
*/
|
|
XND_LINK XND_USER_FIND_IDX XND_API xnd_get_user_list_idx_start(XND_DEVICE_CONTEXT dev_ctx);
|
|
//\cond NOT_COMMENTED
|
|
XND_LINK int XND_API xnd_reserved3(XND_DEVICE_CONTEXT dev_ctx, void* xnd_user_find);
|
|
//\endcond
|
|
|
|
/**
|
|
\ingroup xnd_list_username_idx
|
|
Return the next username and its index from the list of normal users (see \ref xnd_users_types) present on an xNodus device.
|
|
\param[in] xnd_find an handle of type ::XND_USER_FIND_IDX returned by xnd_get_user_list_idx_start().
|
|
\param[out] user_name points to a structure of type ::XND_USER_NAME that will contain the next username found.
|
|
\param[out] p_user_index points to an unsigned integer that will receive the internal identification index of the user. This entry may be set to 0.
|
|
\return ::XND_ERROR_SUCCESS on success, return XND_ERROR_DEV_USER_NO_MORE_USER_AVAILABLE when no more users are present, an \ref xnodus_errors "error code" on failure.
|
|
\remark The 'Anonymous' and 'Administrator' users (see \ref xnd_users_types) are not listed.
|
|
|
|
\see xnd_get_user_list_idx_start(), xnd_get_user_list_idx_finalize().
|
|
*/
|
|
XND_LINK int XND_API xnd_get_user_list_idx_next(XND_USER_FIND_IDX xnd_find, OPT OUT P_XND_USER_NAME user_name, OPT OUT unsigned int* p_user_index);
|
|
|
|
//\cond NOT_COMMENTED
|
|
XND_LINK int XND_API xnd_reserved4(void* xnd_find, XND_DEVICE_CONTEXT dev_ctx, OPT OUT P_XND_USER_NAME user_name, OPT OUT unsigned int* p_user_index);
|
|
//\endcond
|
|
|
|
/**
|
|
\ingroup xnd_list_username_idx
|
|
Finalize an xNodus username and index search.
|
|
\param[in] xnd_find an handle of type ::XND_USER_FIND_IDX returned by xnd_get_user_list_idx_start().
|
|
\return ::XND_ERROR_SUCCESS on success, an \ref xnodus_errors "error code" on failure.
|
|
\remark This function can be called also before the search has been completed.
|
|
|
|
\see xnd_get_user_list_idx_start(), xnd_get_user_list_idx_next().
|
|
*/
|
|
XND_LINK int XND_API xnd_get_user_list_idx_finalize(XND_USER_FIND_IDX xnd_find);
|
|
|
|
/**
|
|
\ingroup xnd_user_man
|
|
Return user information of an 'Anoymous' or normal user (see \ref xnd_users_types).
|
|
\param[in] dev_ctx a ::XND_DEVICE_CONTEXT handle referring to a device context object with open session.
|
|
\param[in] user_name points to a structure of type ::XND_USER_NAME containing the name of the user to get information.
|
|
\param[out] p_user_info points to structure of type ::XND_USER_INFO containing the user information.
|
|
\return ::XND_ERROR_SUCCESS on success, an \ref xnodus_errors "error code" on failure.
|
|
\remark This function can be called from an adminstrator session to get information of every user, an 'Anoymous' or normal user can get only its own information.
|
|
*/
|
|
XND_LINK int XND_API xnd_get_user_info(XND_DEVICE_CONTEXT dev_ctx, const XND_USER_NAME* user_name, OUT P_XND_USER_INFO p_user_info);
|
|
|
|
/**
|
|
\ingroup xnd_user_man
|
|
Return information of the current 'Anoymous' or normal user (see \ref xnd_users_types).
|
|
\param[in] dev_ctx a ::XND_DEVICE_CONTEXT handle referring to a device context object with open session.
|
|
\param[out] p_user_info points to structure of type ::XND_USER_INFO containing the user information.
|
|
\return ::XND_ERROR_SUCCESS on success, an \ref xnodus_errors "error code" on failure.
|
|
\see xnd_get_user_info().
|
|
*/
|
|
XND_LINK int XND_API xnd_get_current_user_info(XND_DEVICE_CONTEXT dev_ctx, OUT P_XND_USER_INFO p_user_info);
|
|
|
|
/**
|
|
\ingroup xnd_user_man
|
|
Create a normal user (see \ref xnd_users_types).
|
|
\param[in] dev_ctx a ::XND_DEVICE_CONTEXT handle referring to a device context object with open session.
|
|
\param[in] p_user_info points to a structure of type ::XND_USER_INFO containing the configuration settings for the new user.
|
|
\return ::XND_ERROR_SUCCESS on success, an \ref xnodus_errors "error code" on failure.
|
|
\remark It is recommended to set the permission_mask entry of the ::XND_USER_INFO structure with the ::XND_PMASK_USER_DEFAULT value.
|
|
|
|
\remark This function can be called only from an administrator session.
|
|
*/
|
|
XND_LINK int XND_API xnd_create_user(XND_DEVICE_CONTEXT dev_ctx, const XND_USER_INFO* p_user_info);
|
|
|
|
/**
|
|
\ingroup xnd_user_man
|
|
Update an 'Anonymous' or normal user (see \ref xnd_users_types).
|
|
\param[in] dev_ctx a ::XND_DEVICE_CONTEXT handle referring to a device context object with open session.
|
|
\param[in] p_user_info points to a structure of type ::XND_USER_INFO containing the changed configuration settings for the user.
|
|
\return ::XND_ERROR_SUCCESS on success, an \ref xnodus_errors "error code" on failure.
|
|
\remark It is recommended to set the permission_mask entry of the ::XND_USER_INFO structure with the ::XND_PMASK_USER_DEFAULT value for the normal user, and ::XND_PMASK_USER_ANONYMOUS_DEFAULT for the 'Anonymous' user.
|
|
|
|
\remark This function can be called only from an administrator session.
|
|
*/
|
|
XND_LINK int XND_API xnd_update_user(XND_DEVICE_CONTEXT dev_ctx, const XND_USER_INFO* p_user_info);
|
|
|
|
/**
|
|
\ingroup xnd_user_man
|
|
Delete a normal user (see \ref xnd_users_types).
|
|
\param[in] dev_ctx a ::XND_DEVICE_CONTEXT handle referring to a device context object with open session.
|
|
\param[in] user_name points to a structure of type ::XND_USER_NAME containing the name of the normal user to be deleted.
|
|
\return ::XND_ERROR_SUCCESS on success, an \ref xnodus_errors "error code" on failure.
|
|
\remark This function can be called only from an administrator session.
|
|
*/
|
|
XND_LINK int XND_API xnd_delete_user(XND_DEVICE_CONTEXT dev_ctx, const XND_USER_NAME* user_name);
|
|
|
|
/**
|
|
\ingroup xnd_user_man
|
|
Change the cryptographic key of a normal user (see \ref xnd_users_types).
|
|
\param[in] dev_ctx a ::XND_DEVICE_CONTEXT handle referring to a device context object with open session.
|
|
\param[in] user_name points to a structure of type ::XND_USER_NAME containing the name of the normal user for which the password must be changed.
|
|
\param[in] key_type key type of the new key. This value takes values from \ref xnd_info_key_type.
|
|
\param[in] key points to the buffer containing the new key. It must be a PQE formatted key or XLight style RSA key (see \ref xnd_key_data)
|
|
\param[in] key_len the length in bytes of the new key.
|
|
\return ::XND_ERROR_SUCCESS on success, an \ref xnodus_errors "error code" on failure.
|
|
\remark The administrator user can change the key of every normal user but not its own key (the only way to change the administrator password is to reprogram the xNodus device). Each normal user can change only its own password.
|
|
*/
|
|
XND_LINK int XND_API xnd_change_user_key(XND_DEVICE_CONTEXT dev_ctx, const XND_USER_NAME* user_name, unsigned int key_type, const unsigned char* key, unsigned int key_len);
|
|
|
|
/**
|
|
\ingroup xnd_functions
|
|
Start the Secure Boot Loader (SBL) of the device (see \ref xnd_sbl).
|
|
\param[in] dev_ctx a ::XND_DEVICE_CONTEXT handle referring to a device context object with open session.
|
|
\return ::XND_ERROR_SUCCESS on success, an \ref xnodus_errors "error code" on failure.
|
|
\remark This function can be called from an administrator session. It can be called also from an 'Anonymous' or normal user if the permission mask allows this task (used ::XND_PMASK_SS_START_SBL).
|
|
*/
|
|
XND_LINK int XND_API xnd_start_sbl(XND_DEVICE_CONTEXT dev_ctx);
|
|
|
|
/**
|
|
\ingroup xnd_functions
|
|
Immediately close all open sessions except that of the function caller. Usually only the administrator user is allowed to call this function.
|
|
\param[in] dev_ctx a ::XND_DEVICE_CONTEXT handle referring to a device context object with open session.
|
|
\return ::XND_ERROR_SUCCESS if found, an \ref xnodus_errors "error code" on failure.
|
|
\remark This function can be called from an administrator session.
|
|
*/
|
|
XND_LINK int XND_API xnd_close_all_sessions(XND_DEVICE_CONTEXT dev_ctx);
|
|
|
|
/**
|
|
\ingroup xnd_functions
|
|
Virginize a virtual XLight device (see \ref xnd_virtual_xlight).
|
|
|
|
This function restore a virtual XLight of an xNodus device to its non programmed state.
|
|
|
|
It is analogous to the xnd_xlt_virg_demo() applied on real XLight device with the relevant difference that in this case it can be applied to every non demo device.
|
|
\param[in] dev_ctx a ::XND_DEVICE_CONTEXT handle referring to a device context object with open session.
|
|
\param[in] xlight_index index of the virtual XLight to be virginized.
|
|
\return ::XND_ERROR_SUCCESS on success, an \ref xnodus_errors "error code" on failure.
|
|
\remark This function can be called by the Administrator user. 'Anonymous' and normal users also can call this function as well but the default and suggested permission settings prevent them to run this function.
|
|
Whenever the permission is given also to these users they can just virginize only their own virtual XLight device.
|
|
*/
|
|
XND_LINK int XND_API xnd_virginize_xlight(XND_DEVICE_CONTEXT dev_ctx, unsigned int xlight_index);
|
|
|
|
/**
|
|
\ingroup xnd_non_volatile_g
|
|
Set a non-volatile cryptographic key on an xNodus device (see \ref xnd_non_volatile).
|
|
\param[in] dev_ctx a ::XND_DEVICE_CONTEXT handle referring to a device context object with open session.
|
|
\param[in] key_type key type of the passed key. This value takes values from \ref xnd_info_key_type.
|
|
\param[in] key points to the buffer containing the non volatile key. It must be a PQE formatted key or XLight style RSA key (see \ref xnd_key_data)
|
|
\param[in] key_len the length in bytes of the key.
|
|
\return ::XND_ERROR_SUCCESS on success, an \ref xnodus_errors "error code" on failure.
|
|
\remark This function can be called by the Administrator user. 'Anonymous' and normal users also can call this function as well but the default and suggested permission settings prevent them to run this function.
|
|
|
|
\remark It is possible to perform the volatile key setting also using a remote command using xnd_remote_cmd_non_volatile_key_set() and
|
|
\see xnd_non_volatile_encrypt(), xnd_non_volatile_decrypt().
|
|
*/
|
|
XND_LINK int XND_API xnd_non_volatile_key_set(XND_DEVICE_CONTEXT dev_ctx, unsigned int key_type, const unsigned char* key, unsigned int key_len);
|
|
|
|
/**
|
|
\ingroup xnd_non_volatile_g
|
|
Perform a RSA encryption using a non-volatile key (see \ref xnd_non_volatile).
|
|
\param[in] dev_ctx a ::XND_DEVICE_CONTEXT handle referring to a device context object with open session.
|
|
\param[in] key_type type of the key to be used. The type identify also which key must be kept. This value takes values from \ref xnd_info_key_type.
|
|
\param[in] plaintext points to a buffer containing the data to encrypt.
|
|
\param[in] plaintext_len the length of the plaintext. It must be equal to the byte length of the key (for instance 256 bytes for a 2048 bit key).
|
|
\param[out] ciphertext points to a buffer that will receive the encrypted data. The returned buffer has the same length of the plaintext.
|
|
\return ::XND_ERROR_SUCCESS on success, an \ref xnodus_errors "error code" on failure.
|
|
\see xnd_non_volatile_key_set(), xnd_non_volatile_decrypt().
|
|
*/
|
|
XND_LINK int XND_API xnd_non_volatile_encrypt(XND_DEVICE_CONTEXT dev_ctx, unsigned int key_type, const unsigned char* plaintext, unsigned int plaintext_len, unsigned char* ciphertext);
|
|
|
|
/**
|
|
\ingroup xnd_non_volatile_g
|
|
Perform a RSA decryption using a non-volatile key (see \ref xnd_non_volatile).
|
|
\param[in] dev_ctx a ::XND_DEVICE_CONTEXT handle referring to a device context object with open session.
|
|
\param[in] key_type type of the key to be used. The type identify also which key must be kept. This value takes values from \ref xnd_info_key_type.
|
|
\param[in] ciphertext points to a buffer containing the data to decrypt.
|
|
\param[in] ciphertext_len the length of the ciphertext. It must be equal to the byte length of the key (for instance 256 bytes for a 2048 bit key).
|
|
\param[out] plaintext points to a buffer that will receive the decrypted data. The returned buffer has the same length of the ciphertext.
|
|
\return ::XND_ERROR_SUCCESS on success, an \ref xnodus_errors "error code" on failure.
|
|
\see xnd_non_volatile_key_set(), xnd_non_volatile_encrypt().
|
|
*/
|
|
XND_LINK int XND_API xnd_non_volatile_decrypt(XND_DEVICE_CONTEXT dev_ctx, unsigned int key_type, const unsigned char* ciphertext, unsigned int ciphertext_len, unsigned char* plaintext);
|
|
|
|
/**
|
|
\ingroup xnd_functions
|
|
Change the permissions of a user (see \ref xnd_users_types).
|
|
\param[in] dev_ctx a ::XND_DEVICE_CONTEXT handle referring to a device context object with open session.
|
|
\param[in] user_name points to a structure of type ::XND_USER_NAME with the name of the user to which the permission mask must be changed
|
|
\param[in] mask the new permission mask composed with bitwise OR of a collection of values from \ref xnd_permision_mask.
|
|
\return ::XND_ERROR_SUCCESS on success, an \ref xnodus_errors "error code" on failure.
|
|
\remark This function can be called only by the Administrator user.
|
|
*/
|
|
XND_LINK int XND_API xnd_set_permission_mask(XND_DEVICE_CONTEXT dev_ctx, const XND_USER_NAME* user_name, XLT_ULONG_LONG mask);
|
|
|
|
/**
|
|
\ingroup xnd_volatile_g
|
|
Wrap a non-volatile key (see \ref xnd_volatile).
|
|
\param[in] dev_ctx ::XND_DEVICE_CONTEXT handle referring to a real or fake device.
|
|
\param[in] key points to the AES key that must be used onto xNodus.
|
|
\param[in] key_len length in byte of the AES key.
|
|
\param[in] service_key the 32 byte key set by xnd_init_device().
|
|
\param[out] wrapped_key_32 points to a 32 byte buffer that will receive the result of the AES key wrapping.
|
|
\return ::XND_ERROR_SUCCESS on success, an \ref xnodus_errors "error code" on failure.
|
|
\remark Never use this function inside the protected program.
|
|
*/
|
|
XND_LINK int XND_API xnd_volatile_key_wrap(XND_DEVICE_CONTEXT dev_ctx, const unsigned char* key, unsigned int key_len, const unsigned char* service_key, unsigned char* wrapped_key_32);
|
|
|
|
/**
|
|
\ingroup xnd_volatile_g
|
|
Set a volatile key inside the xNodus device (see \ref xnd_volatile).
|
|
\param[in] dev_ctx a ::XND_DEVICE_CONTEXT handle referring to a device context object with open session.
|
|
\param[in] wrapped_key points to a 32 byte buffer containing the AES key wrapped with the xnd_volatile_key_wrap() function.
|
|
\return ::XND_ERROR_SUCCESS on success, an \ref xnodus_errors "error code" on failure.
|
|
*/
|
|
XND_LINK int XND_API xnd_volatile_key_set(XND_DEVICE_CONTEXT dev_ctx, const unsigned char* wrapped_key);
|
|
|
|
/**
|
|
\defgroup xnd_encryption_mode Encryption mode of operation of the volatile encryption functions.
|
|
\ingroup xnodus_defines
|
|
The supported encryption modes are:
|
|
<ol>
|
|
<li> ECB (Electronic Codebook mode)
|
|
<li> CBC (Cipher Block Chaining)
|
|
<li> IGE (Infinite Garble Extension)
|
|
<li> GCM (Galois Counter Mode)
|
|
</ol>
|
|
|
|
@{
|
|
*/
|
|
#define XND_ENCRYPTION_MODE_ECB 0 ///< ECB encryption mode
|
|
#define XND_ENCRYPTION_MODE_CBC 1 ///< CBC encryption mode
|
|
#define XND_ENCRYPTION_MODE_IGE 2 ///< IGE encryption mode
|
|
#define XND_ENCRYPTION_MODE_GCM 3 ///< GCM encryption mode
|
|
|
|
//@} //xnd_encryption_mode
|
|
|
|
/**
|
|
\ingroup xnd_volatile_g
|
|
Perform a volatile encryption (see \ref xnd_volatile).
|
|
\param[in] dev_ctx a ::XND_DEVICE_CONTEXT handle referring to a device context object with open session.
|
|
\param[in] key_byte_len the length in byte of the AES key (32, 24 or 16).
|
|
\param[in] mode_of_operation mode of operation of the encryption selected using the values from /ref xnd_encryption_mode.
|
|
\param[in] plaintext points to the buffer containing the data to encrypt.
|
|
\param[in] plaintext_len the length of the plaintext. This value must be a multiple of 16.
|
|
\param[in] ini_vect points to buffer containing the initialization vector for the CBC or GCM mode. In case of CBC 16 bytes will be considered, while for GCM 12 bytes are taken. This entry may be set to 0 for ECB, IGE and also for CBC mode.
|
|
\param[in] gcm_aad_len the length of the AAD (additional authenticated data) part of the plaintext when using GCM. The AAD part is the heading part of the plaintext buffer and its length must be not grater than the plaintext length. 'gcm_aad_len' must be set to '0' using the other encryption modes and can be set to 0 with GCM. This value must be a multiple of 16.
|
|
\param[out] ciphertext points to a buffer that will receive the result of the encryption operation.
|
|
\param[in] ciphertext_size the length in bytes of the buffer pointed by the 'ciphertext' argument.
|
|
\param[out] p_ciphertext_len points to a buffer that will receive the length of the returned ciphertext.
|
|
\return ::XND_ERROR_SUCCESS on success, an \ref xnodus_errors "error code" on failure.
|
|
The original GCM doesn't have the restrictions present here (including the multiple of 16 requests) to exploit the hardware encryption supplied by the device.
|
|
\note Every user can run this function.
|
|
*/
|
|
XND_LINK int XND_API xnd_volatile_encrypt(XND_DEVICE_CONTEXT dev_ctx, unsigned int key_byte_len, unsigned int mode_of_operation, const unsigned char* plaintext, unsigned int plaintext_len, OPT const unsigned char* ini_vect, OPT unsigned int gcm_aad_len, unsigned char* ciphertext, unsigned int ciphertext_size, OPT OUT unsigned int* p_ciphertext_len);
|
|
|
|
/**
|
|
\ingroup xnd_volatile_g
|
|
Perform a volatile decryption (see \ref xnd_volatile).
|
|
\param[in] dev_ctx a ::XND_DEVICE_CONTEXT handle referring to a device context object with open session.
|
|
\param[in] key_byte_len the length in byte of the AES key (32, 24 or 16).
|
|
\param[in] mode_of_operation mode of operation of the encryption selected using the values from /ref xnd_encryption_mode.
|
|
\param[in] ciphertext points to a buffer containing the data to be decrypted.
|
|
\param[in] ciphertext_len the length of the ciphertext. This value must be a multiple of 16.
|
|
\param[in] ini_vect points to buffer containing the initialization vector for the CBC or GCM mode. In case of CBC 16 bytes will be considered, while for GCM 12 bytes are taken. This entry may be set to 0 for ECB, IGE and also for CBC mode.
|
|
\param[in] gcm_aad_len the length of the AAD (additional authenticated data) part of the plaintext when using GCM. The AAD part is the heading part of the plaintext buffer and its length must be not grater than the plaintext length. 'gcm_aad_len' must be set to '0' using the other encryption modes and can be set to 0 with GCM. This value must be a multiple of 16.
|
|
\param[out] plaintext points to a buffer that will receive the result of the decryption operation.
|
|
\param[in] plaintext_size the length in bytes of the buffer pointed by the 'plaintext' argument.
|
|
\param[out] p_plaintext_len points to a buffer that will receive the length of the returned plaintext.
|
|
\return ::XND_ERROR_SUCCESS on success, an \ref xnodus_errors "error code" on failure.
|
|
The original GCM doesn't have the restrictions present here (including the multiple of 16 requests) to exploit the hardware encryption supplied by the device.
|
|
\note Every user can run this function.
|
|
*/
|
|
XND_LINK int XND_API xnd_volatile_decrypt(XND_DEVICE_CONTEXT dev_ctx, unsigned int key_byte_len, unsigned int mode_of_operation, const unsigned char* ciphertext, unsigned int ciphertext_len, OPT const unsigned char* ini_vect, OPT unsigned int gcm_aad_len, unsigned char* plaintext, unsigned int plaintext_size, OPT unsigned int* p_plaintext_len);
|
|
|
|
/**
|
|
\ingroup xnd_functions
|
|
Test function for manage the 'session check' procedure system (see \ref xnd_session_check)
|
|
\param[in] key a ::XND_KEY_DATA handle to a cryptographic key corresponding to the used non non volatile key present on xNodus.
|
|
\param[in] counter_value the progressive counter of the session check procedure.
|
|
\param[in] random_data points to the random data needed for the procedure
|
|
\param[in] random_data_len the length of the random data. This value must be 12 for AES encryption or the length of the public module expressed in byte minus '4' when using RSA.
|
|
\param[out] enc_msg points to a buffer that will receive the computed value to be send to the xNodus device.
|
|
\param[in] enc_msg_size the size in byte of the buffer pointed by the 'enc_msg' entry.
|
|
\param[out] p_enc_msg_len points to an unsigned integer that will receive the real length of the computed value written in 'enc_msg'. If set to '0' the length is not retrieved.
|
|
\return ::XND_ERROR_SUCCESS on success, an \ref xnodus_errors "error code" on failure.
|
|
\note This function is present for testing purpose, never use it in the application protected with xNodus.
|
|
\see xnd_start_session_check(), xnd_continue_session_check().
|
|
*/
|
|
XND_LINK int XND_API xnd_never_use_session_check_prepare(XND_KEY_DATA key, unsigned int counter_value, const unsigned char* random_data, unsigned int random_data_len, unsigned char* enc_msg, unsigned int enc_msg_size, unsigned int* p_enc_msg_len);
|
|
|
|
/**
|
|
\ingroup xnd_functions
|
|
Start a 'session check' procedure (see \ref xnd_session_check).
|
|
\param[in] dev_ctx a ::XND_DEVICE_CONTEXT handle referring to a device context object with open session.
|
|
\param[in] key_type key type of the desired non volatile key. This value takes values from \ref xnd_info_key_type.
|
|
\param[in] enc_msg points to a buffer containing the encrypted data that starts the session check procedure (computed by xnd_never_use_session_check_prepare() or, better, equivalent functions).
|
|
\param[in] enc_msg_len the length of the 'enc_msg' entry.
|
|
\param[out] dec_msg points to a buffer that will receive the data produced by by xNodus (a decryption of the incoming data).
|
|
\param[in] dec_msg_size the size in byte of the buffer pointed by the 'dec_msg' entry.
|
|
\param[out] p_dec_msg_len points to an unsigned integer that will receive the real length of the computed value written in 'dec_msg'. If set to '0' the length is not retrieved.
|
|
\return ::XND_ERROR_SUCCESS on success, an \ref xnodus_errors "error code" on failure.
|
|
\see xnd_continue_session_check(), xnd_never_use_session_check_prepare().
|
|
*/
|
|
XND_LINK int XND_API xnd_start_session_check(XND_DEVICE_CONTEXT dev_ctx, unsigned int key_type, const unsigned char* enc_msg, unsigned int enc_msg_len, unsigned char* dec_msg, unsigned int dec_msg_size, unsigned int* p_dec_msg_len);
|
|
|
|
/**
|
|
\ingroup xnd_functions
|
|
Continue a 'session check' procedure (see \ref xnd_session_check).
|
|
\param[in] dev_ctx a ::XND_DEVICE_CONTEXT handle referring to a device context object with open session.
|
|
\param[in] key_type key type of the desired non volatile key. This value takes values from \ref xnd_info_key_type.
|
|
\param[in] enc_msg points to a buffer containing the encrypted data that starts the session check procedure (computed by xnd_never_use_session_check_prepare() or, better, equivalent functions).
|
|
\param[in] enc_msg_len the length of the 'enc_msg' entry.
|
|
\param[out] dec_msg points to a buffer that will receive the data produced by by xNodus (a decryption of the incoming data).
|
|
\param[in] dec_msg_size the size in byte of the buffer pointed by the 'dec_msg' entry.
|
|
\param[out] p_dec_msg_len points to an unsigned integer that will receive the real length of the computed value written in 'dec_msg'. If set to '0' the length is not retrieved.
|
|
\return ::XND_ERROR_SUCCESS on success, an \ref xnodus_errors "error code" on failure.
|
|
\see xnd_start_session_check(), xnd_never_use_session_check_prepare().
|
|
*/
|
|
XND_LINK int XND_API xnd_continue_session_check(XND_DEVICE_CONTEXT dev_ctx, unsigned int key_type, const unsigned char* enc_msg, unsigned int enc_msg_len, unsigned char* dec_msg, unsigned int dec_msg_size, unsigned int* p_dec_msg_len);
|
|
|
|
/**
|
|
\ingroup xnd_functions
|
|
Return a true (hardware) random number.
|
|
\param[in] dev_ctx a ::XND_DEVICE_CONTEXT handle referring to a device context object with open session.
|
|
\param[out] random points to a buffer that will receive the random buffer.
|
|
\param[in] len the length in bytes of the desired random buffer.
|
|
\return ::XND_ERROR_SUCCESS on success, an \ref xnodus_errors "error code" on failure.
|
|
*/
|
|
XND_LINK int XND_API xnd_get_true_random(XND_DEVICE_CONTEXT dev_ctx, OUT unsigned char* random, unsigned int len);
|
|
|
|
/**
|
|
Start SBL (Secure Boot Loader) command structure for remote command
|
|
|
|
This is the structure of the remote start boot loader command.
|
|
In order to perform a remote reboot it is necessary set the serial number (just the final four bytes of the sixteen overall)
|
|
and set a counter greater than the current one. Both values are returned by xnd_get_info().
|
|
|
|
It is suggested to use the unix time for destination_counter: this allow to avoid to read its value and grant to use a value
|
|
greater than the previous one
|
|
|
|
SBL (Secure Boot Loader) is the xNodus configuration that is used to update the firmware: only a OxySec signed firmware can be uploaded.
|
|
When a device is in SBL configuration it can't do anything but update the firmware to a newer version.
|
|
*/
|
|
typedef struct _REMOTE_SBL_CMD {
|
|
unsigned char destination_serial_part[4]; ///< Final four bytes of the device serial number of the destination xNodus device (XND_INFO.sn).
|
|
unsigned int destination_counter; ///< Counter of the operation (must be grater than XND_INFO.remote_counter).
|
|
}REMOTE_SBL_CMD;
|
|
typedef REMOTE_SBL_CMD *P_REMOTE_SBL_CMD; ///< pointer to ::REMOTE_SBL_CMD type
|
|
|
|
|
|
/**
|
|
Start SBL (Secure Boot Loader) response structure for remote command
|
|
|
|
This is the structure of the remote start boot loader command answer. It contains the argument of the command and the status of the operation
|
|
*/
|
|
typedef struct _REMOTE_SBL_RESP {
|
|
REMOTE_SBL_CMD issued_cmd; ///< arguments of the remote start boot loader command sent to the device
|
|
int status; ///< the status of the operation returned by the device
|
|
}REMOTE_SBL_RESP;
|
|
typedef REMOTE_SBL_RESP *P_REMOTE_SBL_RESP; ///< pointer to ::REMOTE_SBL_RESP type
|
|
|
|
/**
|
|
\ingroup xnodus_remote_cmd
|
|
Write a buffer for the remote execution of the start of the Secure Boot Loader on a given device.
|
|
\param[in] dev_ctx an administrator device context object handle.
|
|
\param[in] remote_sbl_cmd points to a structure ::REMOTE_SBL_CMD with the arguments of the command.
|
|
\param[out] enc_cmd points to a buffer that will receive the command buffer to be remotely applied to the device using xnd_apply_remote_command()
|
|
\param[in] enc_cmd_size the size of the buffer pointed by 'enc_cmd'.
|
|
\param[out] p_enc_cmd_len points to an unsigned integer that will receive the length of the command pointed by 'enc_cmd'.
|
|
\return ::XND_ERROR_SUCCESS if found, an \ref xnodus_errors "error code" on failure.
|
|
\remark To apply the command to the xNodus device it is necessary run xnd_apply_remote_command() in an application that can communicate directly to the target xNodus device. As input it needs the generated encrypted command
|
|
(i.e. the result pointed by enc_cmd). If it is necessary to know the result of the operation of xnd_apply_remote_command(), the function xnd_remote_resp_start_sbl() can analyze the response to the command.
|
|
\see xnd_apply_remote_command(), xnd_remote_resp_start_sbl().
|
|
*/
|
|
XND_LINK int XND_API xnd_remote_cmd_start_sbl(XND_DEVICE_CONTEXT dev_ctx, const REMOTE_SBL_CMD* remote_sbl_cmd, OUT unsigned char* enc_cmd, unsigned int enc_cmd_size, OUT unsigned int* p_enc_cmd_len);
|
|
|
|
/**
|
|
\ingroup xnodus_remote_cmd
|
|
Retrieve the status of a remote start 'Secure Boot Loader' call
|
|
\param[in] dev_ctx an administrator device context object handle.
|
|
\param[in] enc_resp points to a buffer containing the response of xNodus returned by the function xnd_apply_remote_command().
|
|
\param[in] enc_resp_len the length of the buffer pointed by 'enc_resp'.
|
|
\param[out] p_resp points to a struct of type ::REMOTE_SBL_RESP that will be filled with the status and data of the remote operation.
|
|
\return ::XND_ERROR_SUCCESS if found, an \ref xnodus_errors "error code" on failure.
|
|
\see xnd_remote_cmd_start_sbl().
|
|
*/
|
|
XND_LINK int XND_API xnd_remote_resp_start_sbl(XND_DEVICE_CONTEXT dev_ctx, const unsigned char* enc_resp, unsigned int enc_resp_len, OUT P_REMOTE_SBL_RESP p_resp);
|
|
|
|
/**
|
|
Non volatile key set command structure for remote command
|
|
|
|
This is the structure of the remote 'non volatile key set' command.
|
|
In order to perform a remote 'non volatile key set' it is necessary (in addition to the key values) set the serial number (just the final four bytes of the sixteen overall)
|
|
and set a counter greater than the current one. Both values are returned by xnd_get_info().
|
|
|
|
It is suggested to use the unix time for destination_counter: this allow to avoid to read its value and grant to use a value
|
|
greater than the previous one
|
|
*/
|
|
typedef struct _REMOTE_NON_VOLATILE_KEY_SET_CMD {
|
|
unsigned int key_type; ///< type of cryptographic key to be set (values from \ref xnd_info_key_type).
|
|
unsigned int key_len; ///< length of cryptographic key
|
|
unsigned char key[XND_RSA_4096_PRIV_KEY_SIZE];///< cryptographic key to be set expressed in XLight or xNodus format (see \ref xnd_key_data).
|
|
unsigned char destination_serial_part[4];///< final four bytes of the xNodus device serial number (XND_INFO.sn).
|
|
unsigned int destination_counter; ///< counter of the operation (must be grater than XND_INFO.remote_counter).
|
|
}REMOTE_NON_VOLATILE_KEY_SET_CMD;
|
|
typedef REMOTE_NON_VOLATILE_KEY_SET_CMD *P_REMOTE_NON_VOLATILE_KEY_SET_CMD; ///< pointer to ::REMOTE_NON_VOLATILE_KEY_SET_CMD type
|
|
|
|
/**
|
|
Non volatile key set response structure for remote command
|
|
|
|
This is the structure of the remote 'non volatile key set' command answer. It contains the argument of the command and the status of the operation
|
|
*/
|
|
typedef struct _REMOTE_NON_VOLATILE_KEY_SET_RESP {
|
|
REMOTE_NON_VOLATILE_KEY_SET_CMD issued_cmd; ///< arguments of the remote non volatile set key command sent to the device
|
|
int status; ///< the status of the operation returned by the device
|
|
}REMOTE_NON_VOLATILE_KEY_SET_RESP;
|
|
typedef REMOTE_NON_VOLATILE_KEY_SET_RESP *P_REMOTE_NON_VOLATILE_KEY_SET_RESP; ///< pointer to ::REMOTE_NON_VOLATILE_KEY_SET_RESP type
|
|
|
|
/**
|
|
\ingroup xnodus_remote_cmd
|
|
Set a non volatile key remotely.
|
|
|
|
Construct a remote command buffer to perform the same task of the xnd_non_volatile_key_set() function.
|
|
\param[in] dev_ctx an administrator device context object handle.
|
|
\param[in] cmd points to a structure ::REMOTE_NON_VOLATILE_KEY_SET_CMD with the arguments of the command.
|
|
\param[out] enc_cmd points to a buffer that will receive the command buffer to be remotely applied to the device using xnd_apply_remote_command().
|
|
\param[in] enc_cmd_size the size of the buffer pointed by 'enc_cmd'.
|
|
\param[out] p_enc_cmd_len points to an unsigned integer that will receive the length of the command pointed by 'enc_cmd'.
|
|
\return ::XND_ERROR_SUCCESS if found, an \ref xnodus_errors "error code" on failure.
|
|
\remark To apply the command to the xNodus device it is necessary run xnd_apply_remote_command() in an application that can communicate directly to the target xNodus device. As input it needs the generated encrypted command
|
|
(i.e. the result pointed by enc_cmd). If it is necessary to know the result of the operation of xnd_apply_remote_command(), the function xnd_remote_resp_non_volatile_key_set() can analyze the response to the command.
|
|
\see xnd_remote_resp_non_volatile_key_set(), xnd_apply_remote_command().
|
|
*/
|
|
XND_LINK int XND_API xnd_remote_cmd_non_volatile_key_set(XND_DEVICE_CONTEXT dev_ctx, const REMOTE_NON_VOLATILE_KEY_SET_CMD* cmd, OUT unsigned char* enc_cmd, unsigned int enc_cmd_size, OUT unsigned int* p_enc_cmd_len);
|
|
|
|
/**
|
|
\ingroup xnodus_remote_cmd
|
|
|
|
Retrieve the status of a remote 'non volatile key set' command.
|
|
\param[in] dev_ctx an administrator device context object handle.
|
|
\param[in] enc_resp points to a buffer containing the response of xNodus returned by the function xnd_apply_remote_command().
|
|
\param[in] enc_resp_len the length of the buffer pointed by 'enc_resp'.
|
|
\param[out] p_resp points to a struct of type ::REMOTE_NON_VOLATILE_KEY_SET_RESP that will be filled with the status and data of the remote operation.
|
|
\return ::XND_ERROR_SUCCESS if found, an \ref xnodus_errors "error code" on failure.
|
|
|
|
\see xnd_remote_cmd_non_volatile_key_set(), xnd_apply_remote_command().
|
|
*/
|
|
XND_LINK int XND_API xnd_remote_resp_non_volatile_key_set(XND_DEVICE_CONTEXT dev_ctx, const unsigned char* enc_resp, unsigned int enc_resp_len, OUT P_REMOTE_NON_VOLATILE_KEY_SET_RESP p_resp);
|
|
|
|
|
|
/**
|
|
User create and update command structure for remote command
|
|
|
|
This is the structure of the remote 'create user' (see xnd_create_user()) and 'update user' command (see xnd_update_user()).
|
|
In order to perform a remote 'create user' or 'update user' it is necessary set the serial number (just the final four bytes of the sixteen overall)
|
|
and set a counter greater than the current one. Both values are returned by xnd_get_info().
|
|
|
|
It is suggested to use the unix time for destination_counter: this allow to avoid to read its value and grant to use a value
|
|
greater than the previous one
|
|
*/
|
|
typedef struct _REMOTE_UPDATE_USER_CMD {
|
|
unsigned int is_update; ///< if set to 0 this is a remote 'create user' command, otherwise it is an 'update user' command
|
|
unsigned int _unused; ///< unused
|
|
XND_USER_INFO user_info; ///< value to be set remotely. In case of update the entry set_values_mask can be used to change a subset of values.
|
|
unsigned char destination_serial_part[4];///< final four bytes of the xNodus device serial number(XND_INFO.sn).
|
|
unsigned int destination_counter; ///< counter of the operation (must be grater than XND_INFO.remote_counter).
|
|
}REMOTE_UPDATE_USER_CMD;
|
|
typedef REMOTE_UPDATE_USER_CMD *P_REMOTE_UPDATE_USER_CMD; ///< pointer to ::REMOTE_UPDATE_USER_CMD type
|
|
|
|
/**
|
|
User create and update response structure for remote command
|
|
|
|
This is the structure of the remote user create and update command answer. It contains the argument of the command and the status of the operation
|
|
*/
|
|
typedef struct _REMOTE_UPDATE_USER_RESP {
|
|
REMOTE_UPDATE_USER_CMD issued_cmd; ///< arguments of the 'create and update user' command sent to the device
|
|
int status; ///< the status of the operation returned by the device
|
|
unsigned int _unused; ///< unused
|
|
}REMOTE_UPDATE_USER_RESP;
|
|
typedef REMOTE_UPDATE_USER_RESP *P_REMOTE_UPDATE_USER_RESP; ///< pointer to ::REMOTE_UPDATE_USER_RESP type
|
|
|
|
/**
|
|
\ingroup xnodus_remote_cmd
|
|
Create or update a user remotely.
|
|
|
|
Construct a remote command buffer to perform the same task of the xnd_create_user() or xnd_update_user() functions.
|
|
\param[in] dev_ctx an administrator device context object handle.
|
|
\param[in] cmd points to a structure ::REMOTE_UPDATE_USER_CMD with the arguments of the command.
|
|
\param[out] enc_cmd points to a buffer that will receive the command buffer to be remotely applied to the device using xnd_apply_remote_command().
|
|
\param[in] enc_cmd_size the size of the buffer pointed by 'enc_cmd'.
|
|
\param[out] p_enc_cmd_len points to an unsigned integer that will receive the length of the command pointed by 'enc_cmd'.
|
|
\return ::XND_ERROR_SUCCESS if found, an \ref xnodus_errors "error code" on failure.
|
|
\remark To apply the command to the xNodus device it is necessary run xnd_apply_remote_command() in an application that can communicate directly to the target xNodus device. As input it needs the generated encrypted command
|
|
(i.e. the result pointed by enc_cmd). If it is necessary to know the result of the operation of xnd_apply_remote_command(), the function xnd_remote_resp_update_user() can analyze the response to the command.
|
|
\see xnd_remote_resp_update_user(), xnd_apply_remote_command().
|
|
*/
|
|
XND_LINK int XND_API xnd_remote_cmd_update_user(XND_DEVICE_CONTEXT dev_ctx, const REMOTE_UPDATE_USER_CMD* cmd, OUT unsigned char* enc_cmd, unsigned int enc_cmd_size, OUT unsigned int* p_enc_cmd_len);
|
|
|
|
/**
|
|
\ingroup xnodus_remote_cmd
|
|
|
|
Retrieve the status of a remote 'user create or update' command.
|
|
\param[in] dev_ctx an administrator device context object handle.
|
|
\param[in] enc_resp points to a buffer containing the response of xNodus returned by the function xnd_apply_remote_command().
|
|
\param[in] enc_resp_len the length of the buffer pointed by 'enc_resp'.
|
|
\param[out] p_resp points to a struct of type ::REMOTE_UPDATE_USER_RESP that will be filled with the status and data of the remote operation.
|
|
\return ::XND_ERROR_SUCCESS if found, an \ref xnodus_errors "error code" on failure.
|
|
|
|
\see xnd_remote_cmd_update_user(), xnd_apply_remote_command().
|
|
*/
|
|
XND_LINK int XND_API xnd_remote_resp_update_user(XND_DEVICE_CONTEXT dev_ctx, const unsigned char* enc_resp, unsigned int enc_resp_len, OUT P_REMOTE_UPDATE_USER_RESP p_resp);
|
|
|
|
/**
|
|
Delete user command structure for remote command
|
|
|
|
This is the structure of the remote 'delete user' (see xnd_delete_user()).
|
|
In order to perform a remote 'delete user' it is necessary set the serial number (just the final four bytes of the sixteen overall)
|
|
and set a counter greater than the current one. Both values are returned by xnd_get_info().
|
|
|
|
It is suggested to use the unix time for destination_counter: this allow to avoid to read its value and grant to use a value
|
|
greater than the previous one
|
|
*/
|
|
typedef struct _REMOTE_DELETE_USER_CMD {
|
|
XND_USER_NAME user_name; ///< User to be deleted
|
|
unsigned char destination_serial_part[4];///< final four bytes of the xNodus device serial number (XND_INFO.sn).
|
|
unsigned int destination_counter; ///< counter of the operation (must be grater than XND_INFO.remote_counter).
|
|
}REMOTE_DELETE_USER_CMD;
|
|
typedef REMOTE_DELETE_USER_CMD *P_REMOTE_DELETE_USER_CMD; ///< pointer to ::REMOTE_DELETE_USER_CMD type
|
|
|
|
/**
|
|
Delete user response structure for remote command
|
|
|
|
This is the structure of the remote delete user answer. It contains the argument of the command and the status of the operation
|
|
*/
|
|
typedef struct _REMOTE_DELETE_USER_RESP {
|
|
REMOTE_DELETE_USER_CMD issued_cmd; ///< arguments of the 'delete user' command sent to the device
|
|
int status; ///< the status of the operation returned by the device
|
|
}REMOTE_DELETE_USER_RESP;
|
|
typedef REMOTE_DELETE_USER_RESP *P_REMOTE_DELETE_USER_RESP; ///< pointer to ::REMOTE_DELETE_USER_RESP type
|
|
|
|
/**
|
|
\ingroup xnodus_remote_cmd
|
|
Delete a user remotely.
|
|
|
|
Construct a remote command buffer to perform the same task of the xnd_delete_user().
|
|
\param[in] dev_ctx an administrator device context object handle.
|
|
\param[in] cmd points to a structure ::REMOTE_DELETE_USER_CMD with the arguments of the command.
|
|
\param[out] enc_cmd points to a buffer that will receive the command buffer to be remotely applied to the device using xnd_apply_remote_command().
|
|
\param[in] enc_cmd_size the size of the buffer pointed by 'enc_cmd'.
|
|
\param[out] p_enc_cmd_len points to an unsigned integer that will receive the length of the command pointed by 'enc_cmd'.
|
|
\return ::XND_ERROR_SUCCESS if found, an \ref xnodus_errors "error code" on failure.
|
|
\remark To apply the command to the xNodus device it is necessary run xnd_apply_remote_command() in an application that can communicate directly to the target xNodus device. As input it needs the generated encrypted command
|
|
(i.e. the result pointed by enc_cmd). If it is necessary to know the result of the operation of xnd_apply_remote_command(), the function xnd_remote_resp_delete_user() can analyze the response to the command.
|
|
\see xnd_remote_resp_delete_user(), xnd_apply_remote_command().
|
|
*/
|
|
XND_LINK int XND_API xnd_remote_cmd_delete_user(XND_DEVICE_CONTEXT dev_ctx, const REMOTE_DELETE_USER_CMD* cmd, OUT unsigned char* enc_cmd, unsigned int enc_cmd_size, OUT unsigned int* p_enc_cmd_len);
|
|
|
|
/**
|
|
\ingroup xnodus_remote_cmd
|
|
|
|
Retrieve the status of a remote 'delete user' command.
|
|
\param[in] dev_ctx an administrator device context object handle.
|
|
\param[in] enc_resp points to a buffer containing the response of xNodus returned by the function xnd_apply_remote_command().
|
|
\param[in] enc_resp_len the length of the buffer pointed by 'enc_resp'.
|
|
\param[out] p_resp points to a struct of type ::REMOTE_DELETE_USER_RESP that will be filled with the status and data of the remote operation.
|
|
\return ::XND_ERROR_SUCCESS if found, an \ref xnodus_errors "error code" on failure.
|
|
|
|
\see xnd_remote_cmd_delete_user(), xnd_apply_remote_command().
|
|
*/
|
|
XND_LINK int XND_API xnd_remote_resp_delete_user(XND_DEVICE_CONTEXT dev_ctx, const unsigned char* enc_resp, unsigned int enc_resp_len, OUT P_REMOTE_DELETE_USER_RESP p_resp);
|
|
|
|
/**
|
|
\ingroup xnodus_remote_cmd
|
|
Apply a remote command.
|
|
\param[in] dev_ctx a ::XND_DEVICE_CONTEXT handle referring to a device context object where the session state (open or not) is irrelevant.
|
|
\param[in] send_buf points to a buffer containing the encrypted remote commmand.
|
|
\param[in] send_len the length in bytes of the buffer pointed by 'send_buf'.
|
|
\param[out] p_recv_len points to an unsigned integer that will receive the length of the returned response.
|
|
\param[in] recv_timeout_ms timeout in millisecond of the operation. If this value is set to '0' a default value is taken.
|
|
\param[out] p_ret_status points to an integer receiving the inner status of the executed command: ::XND_ERROR_SUCCESS on success, an \ref xnodus_errors "error code" on failure.
|
|
\return return a buffer that containing the encrypted response to the command.
|
|
\remark The buffer returned by the function must be freed calling xnd_free().
|
|
*/
|
|
XND_LINK unsigned char* XND_API xnd_apply_remote_command(XND_DEVICE_CONTEXT dev_ctx, const unsigned char* send_buf, unsigned int send_len, OPT unsigned int recv_timeout_ms, OUT unsigned int* p_recv_len, OUT int* p_ret_status);
|
|
|
|
/**
|
|
\defgroup xnd_log_mask xNodus Log mask
|
|
\ingroup xnodus_defines
|
|
|
|
Mask values for the information to retrieve by the log functions (see \ref xnd_get_log_list_start())
|
|
These mask values are used as significant bit mask also in the field set_values_mask of the structure ::XND_LOG_DATA
|
|
@{
|
|
*/
|
|
#define XND_LOG_SIGNIFICANT_MASK_LICENSE_ID_HASH 0x00000001 ///< license_id_hash entry in ::XND_LOG_DATA is significant
|
|
#define XND_LOG_SIGNIFICANT_MASK_OPEN_INSTANCES 0x00000002 ///< num_open_instances entry in ::XND_LOG_DATA is significant
|
|
#define XND_LOG_SIGNIFICANT_MASK_USER_IDX 0x00000004 ///< user_idx entry in ::XND_LOG_DATA is significant
|
|
#define XND_LOG_SIGNIFICANT_MASK_USER_NAME 0x00000008 ///< user_name entry in ::XND_LOG_DATA is significant
|
|
#define XND_LOG_SIGNIFICANT_MASK_CLIENT_IP 0x00000010 ///< ip_addr entry in ::XND_LOG_DATA is significant
|
|
#define XND_LOG_SIGNIFICANT_MASK_OPEN_MODULES 0x00000020 ///< open_modules entry in ::XND_LOG_DATA is significant
|
|
//@} //xnd_log_mask
|
|
|
|
/**
|
|
\ingroup xnodus_defines
|
|
minimum information data mask that can be retrieved by the log functions
|
|
*/
|
|
#define XND_LOG_MASK_MIN (XND_LOG_SIGNIFICANT_MASK_LICENSE_ID_HASH | XND_LOG_SIGNIFICANT_MASK_OPEN_INSTANCES)
|
|
|
|
/**
|
|
\ingroup xnodus_defines
|
|
complete information data mask that can be retrieved by the log functions
|
|
*/
|
|
#define XND_LOG_SIGNIFICANT_MASK_ALL (XND_LOG_SIGNIFICANT_MASK_LICENSE_ID_HASH | XND_LOG_SIGNIFICANT_MASK_OPEN_INSTANCES | \
|
|
XND_LOG_SIGNIFICANT_MASK_USER_IDX | XND_LOG_SIGNIFICANT_MASK_USER_NAME | XND_LOG_SIGNIFICANT_MASK_CLIENT_IP | XND_LOG_SIGNIFICANT_MASK_OPEN_MODULES)
|
|
|
|
/**
|
|
\ingroup xnodus_defines
|
|
Length of the License identifier value inside the structure ::XND_LOG_DATA
|
|
*/
|
|
#define XND_LOG_ID_HASH_LEN 4
|
|
|
|
/**
|
|
\ingroup xnodus_log
|
|
Log structure,
|
|
Description of the status of a given using license instance.
|
|
In case multi-instance (see \ref xnd_users_group_lic) is not used this values represent the data of an open session, in case
|
|
of multi-instance usage it collects the description of the sum of the session that are using a specific license instance.
|
|
|
|
The entry num_open_instances counts the number of session referring to the license instance.
|
|
|
|
*/
|
|
typedef struct _XND_LOG_DATA{
|
|
unsigned int set_values_mask;///<mask of the significant values of the structure (see \ref xnd_log_mask)
|
|
/**
|
|
identifier of the license instance. It groups a number of sessions sharing the same license, this group contains only one entry unless multi-instance (see \ref xnd_users_group_lic) is used.
|
|
When the multi-instance is not used (the default) this value can be considered as a sort of identification code of a session:
|
|
'license_id_hash' allows understanding if two successive presences of a user in a log correspond to the same session,
|
|
if 'license_id_hash' differs this means that the log refers to different sessions of the user (that is the previous was closed and the latter is the current one).
|
|
Multiple sessions of the same user have different 'license_id_hash'.
|
|
In case of multi-instance session opened from the same machine may be registered with a single 'license_id_hash', but in this case the 'num_open_instances' entry is different from '1'.
|
|
*/
|
|
unsigned char license_id_hash[XND_LOG_ID_HASH_LEN];
|
|
unsigned int num_open_instances; ///< number of open instances of the current license instance
|
|
unsigned int user_idx;///< user identifier
|
|
unsigned char user_name[XND_USER_NAME_LEN];///< user name
|
|
XND_IN_ADDR ip_addr;///< IPv4 address of the connected client using the license
|
|
unsigned char open_modules[XND_MAX_NUM_MODULES];///< mask of the open module
|
|
}XND_LOG_DATA;
|
|
typedef XND_LOG_DATA *P_XND_LOG_DATA;///< pointer to the ::XND_LOG_DATA structure
|
|
|
|
struct _XND_LOG_LIST;
|
|
|
|
/**
|
|
\ingroup xnd_objects
|
|
|
|
Log handle object
|
|
|
|
This is an handle that refers to a log of the current session/license-session on the xLight device (see \ref xnodus_log).
|
|
*/
|
|
typedef struct _XND_LOG_LIST *XND_LOG_LIST;
|
|
|
|
/**
|
|
\ingroup xnodus_log
|
|
Initialize an xNodus log list retrieval performed by xnd_get_log_list_next()
|
|
\param[in] dev_ctx a ::XND_DEVICE_CONTEXT handle referencing the xNodus to query. The device context must be in open session state, and the user must have the permission to get the log information ::XND_PMASK_SS_GET_LOG_LIST.
|
|
\param[in] mask the mask values from \ref xnd_log_mask to instruct xNodus which log information to return.
|
|
\return return a ::XND_LOG_LIST handle.
|
|
\remark only authorized users can perform the log (flag XND_PMASK_SS_GET_LOG_LIST in \ref xnd_permision_mask set).
|
|
\see xnd_get_log_list_next().
|
|
*/
|
|
XND_LINK XND_LOG_LIST XND_API xnd_get_log_list_start(XND_DEVICE_CONTEXT dev_ctx, unsigned int mask);
|
|
//\cond NOT_COMMENTED
|
|
XND_LINK int XND_API xnd_reserved5(XND_DEVICE_CONTEXT dev_ctx, unsigned int mask, XND_LOG_LIST log_list);
|
|
//\endcond
|
|
|
|
/**
|
|
\ingroup xnodus_log
|
|
Perform the xNodus log procedure returning a log record related to a license instance currently running on the xNodus device.
|
|
Repeatedly calling this function the entire log list is returned.
|
|
\param[in] dev_ctx a ::XND_DEVICE_CONTEXT handle. It must be the same uses with xnd_get_log_list_start().
|
|
\param[in] xnd_log a ::XND_LOG_LIST handle returned by a previous call of xnd_get_log_list_start().
|
|
\param[out] p_log_data points to a structure of type ::XND_LOG_DATA containing a single record information of the log list.
|
|
\return ::XND_ERROR_SUCCESS on success, return ::XND_ERROR_LICENSE_LOG_END when the log is finished, an \ref xnodus_errors "error code" on failure.
|
|
\remark It is necessary complete the log procedure running xnd_get_log_list_finalize().
|
|
\see xnd_get_log_list_start(), xnd_get_log_list_finalize().
|
|
*/
|
|
XND_LINK int XND_API xnd_get_log_list_next(XND_DEVICE_CONTEXT dev_ctx, XND_LOG_LIST xnd_log, OUT P_XND_LOG_DATA p_log_data);
|
|
|
|
/**
|
|
\ingroup xnodus_log
|
|
Finalize the xNodus log procedure, and free the related allocated memory.
|
|
\param[in] xnd_log a ::XND_LOG_LIST handle returned by a previous call of xnd_get_log_list_start().
|
|
\return ::XND_ERROR_SUCCESS on success, an \ref xnodus_errors "error code" on failure.
|
|
\see xnd_get_log_list_start(), xnd_get_log_list_next().
|
|
*/
|
|
XND_LINK int XND_API xnd_get_log_list_finalize(XND_LOG_LIST xnd_log);
|
|
|
|
|
|
//xnd_xlt_functions
|
|
/**
|
|
\ingroup xnd_xlt_device
|
|
Return a device context to an XLight device with a specified label.
|
|
\note Neither xNodus devices, nor virtual XLight are recognized
|
|
\param[in] env xNodus environment handle (see xnd_xlt_env_create()).
|
|
\param[in] label buffer of length ::XLT_LABEL_SIZE.
|
|
\param[out] p_status points to an integer that will receive the status of the operation: ::XND_ERROR_SUCCESS on success, an \ref xnodus_errors "error code" on failure.
|
|
considered as a string but as an array of characters of length ::XLT_LABEL_SIZE.
|
|
\return a ::XND_DEVICE_CONTEXT handle referring to the created device context object connected to the searched XLight device. If no device is found a 0 value is returned.
|
|
\note If more than one devices with the same label are present it is returned the device context to the first device found.
|
|
\remark The returned ::XND_DEVICE_CONTEXT handle must be released calling xnd_xlt_devctx_release().
|
|
See \ref simple_example_using_xlight_locate "here" for an example of usage
|
|
*/
|
|
XND_LINK XND_DEVICE_CONTEXT XND_API xnd_xlt_locate(XND_XLT_ENV env, const unsigned char* label, OPT int* p_status);
|
|
|
|
/**
|
|
\ingroup xnd_xlt_device
|
|
* Return information about the selected XLight device.
|
|
* \param[in] dev_ctx ::XND_DEVICE_CONTEXT handle referring to the selected device.
|
|
* \param[out] pversion points to an unsigned int where the version number of the device must be returned. If <i>pversion</i> is NULL this parameter is ignored.
|
|
* \param[out] pmodel points to an unsigned int where the device model identification code must be returned. If <i>pmodel</i> is NULL this parameter is ignored.
|
|
* \param[out] pflags points to an unsigned int where the \ref Flags of the device must be returned. If <i>pflags</i> is NULL this parameter is ignored.
|
|
* \param[out] pserial points to an unsigned int where the serial number of the device must be returned. If <i>pserial</i> is NULL this parameter is ignored.
|
|
* \param[out] label points to the memory location where the label of the device must be returned. If <i>label</i> is NULL this parameter is ignored.
|
|
\return returns ::XLT_ERROR_SUCCESS on success, an \ref xlt_Errors "error code" on failure.
|
|
The user must not rely on this number to infer the order of insertion or the physical position of an XLight device in the USB HUB of the host computer.
|
|
|
|
\par Example
|
|
\code
|
|
#include "xnd.h"
|
|
#include <stdio.h>
|
|
|
|
...
|
|
|
|
int status;
|
|
unsigned int version;
|
|
unsigned int model;
|
|
unsigned int flags;
|
|
unsigned int serial;
|
|
unsigned char label_printable[XLT_LABEL_SIZE + 1];
|
|
int i;
|
|
unsigned int device;
|
|
XND_DEVICE_CONTEXT dev_ctx = 0;
|
|
XND_XLT_ENV env = xnd_xlt_env_create();
|
|
if (!env){
|
|
printf("An error has occurred running xnd_xlt_env_create()!\n");
|
|
goto end;
|
|
}
|
|
|
|
for(device = 0; device < XLT_DEVICE_MAX; device++){
|
|
dev_ctx = xnd_xlt_devctx_xlight_create(env, device, 0, 0, &status);
|
|
if (status != XND_ERROR_SUCCESS){
|
|
//this shouldn't happen!
|
|
printf("Error running xnd_xlt_devctx_xlight_create() - error code: %d\n", status);
|
|
goto end;
|
|
}
|
|
|
|
status = xnd_xlt_getinfo(dev_ctx, &version, &model, &flags, &serial, label_printable);
|
|
if (status == XLT_ERROR_NOT_FOUND)
|
|
printf("Device not found at index %d!\n", device);
|
|
else if (status != XLT_ERROR_SUCCESS)
|
|
printf("An error has occurred!\n");
|
|
else {
|
|
printf("An XLight device was found plugged into the logical port %d\n", device);
|
|
printf("Version: %x.%02x\n", version >> 8, version & 0xFF);
|
|
if (model != XLT_MODEL_BASIC_USBHID)
|
|
printf("Unrecognized model!\n");
|
|
if (flags & XLT_FLAG_SETUP){
|
|
printf("The device is initialized\n");
|
|
for(i = 0; i < XLT_NUMBER_OF_BANKS; i++){
|
|
if (flags & (XLT_FLAG_FROZEN_BANK0 << i))
|
|
printf("Bank %d frozen\n", i);
|
|
}
|
|
}
|
|
else
|
|
printf("The device is NOT initialized\n");
|
|
|
|
printf("The device Serial Number is: 0x%x\n", serial);
|
|
label_printable[XLT_LABEL_SIZE] = 0;
|
|
//N.B.: a label may contain not printable character
|
|
printf("Label: %s\n", (char*) label_printable);
|
|
}
|
|
xnd_xlt_devctx_release(dev_ctx);
|
|
dev_ctx = 0;
|
|
}
|
|
...
|
|
end:
|
|
xnd_xlt_devctx_release(dev_ctx);
|
|
xnd_xlt_env_free(env);
|
|
...
|
|
\endcode
|
|
|
|
*/
|
|
XND_LINK int XND_API xnd_xlt_getinfo(XND_DEVICE_CONTEXT dev_ctx, unsigned int* pversion, unsigned int* pmodel, unsigned int* pflags, unsigned int* pserial, unsigned char* label);
|
|
|
|
|
|
/**
|
|
\ingroup xnd_xlt_device
|
|
Set the label, the password and the cryptographic keys of the device.
|
|
<p>
|
|
<strong>Warning! This function can be executed only once!</strong> All the subsequent calls will fail.
|
|
\note <b> This function produces an irreversible setting onto the XLight device, hence use it very carefully.</b>
|
|
<p>
|
|
|
|
\param[in] dev_ctx ::XND_DEVICE_CONTEXT handle referring to the selected device.
|
|
\param[in] label points to a buffer of length ::XLT_LABEL_SIZE. It contains the label, that is the identification name to be assigned to the device.
|
|
\param[in] password points to a buffer of length ::XLT_PASSWORD_SIZE. It contains the password to be assigned to the device.
|
|
\param[in] dongle_key points to a buffer of length ::XLT_KEY_SIZE. It contains <i>Dongle Key</i>: the AES-256 key that will be used, for instance, by the functions xnd_xlt_session_wrap_key() and xnd_xlt_rsa_wrap_privkey().
|
|
\param[in] cr_key points to a buffer of length ::XLT_KEY_SIZE. It contains an AES-256 key (<i>Challenge Key</i>) that will be used by the function xnd_xlt_challenge().
|
|
\return returns ::XLT_ERROR_SUCCESS on success, an \ref xlt_Errors "error code" on failure.
|
|
|
|
\remark <i>password</i>, <i>dongle_key</i> (the <i>Dongle Key</i>) and <i>cr_key</i> (the <i>Challenge Response Key</i> or shortly <i>Challenge Key</i>) are optional arguments and they can be set to 0 (NULL).
|
|
Whenever one of these entry is null it is considered as if it was an array of bytes filled with the value 0xFF (255 decimal). In other word, passing NULL is equivalent of passing a 0xFF bytes array.
|
|
\note though <i>password</i>, <i>Dongle Key</i> and <i>Challenge Key</i> are optional, it is strongly recommended to set them with non trivial values
|
|
to forbid memory access (using <i>password</i>) to unauthorized application, and to allow the protected application to make sure of the presence of the XLight device with cryptography
|
|
that uses <i>Dongle Key</i> as the base to wrap the \ref xn_RSA_Protection "RSA" and \ref xn_AES_Session_Key "AES session" keys which constitutes the key point of the software protection.
|
|
|
|
\parblock
|
|
\note before calling xnd_xlt_setup() a device is in a non initialized state. In this context only the function xnd_xlt_getinfo() works.
|
|
\endparblock
|
|
\parblock
|
|
\note Never put <i>Dongle Key</i> inside the protected application. This is a key on which many security features are based on, inserting it inside the
|
|
protected application may yield fundamental information to hackers for emulating the <i>XLight</i> device also in its more advanced feaures.
|
|
\endparblock
|
|
\parblock
|
|
\note Never put xnd_xlt_setup() inside the protected application as well: this function can be called from some initialization code used in
|
|
safe environment. If you don't need to manage special setup procedure you can avoid to use this function and rely on the utilities supplied by OxySec.
|
|
\endparblock
|
|
|
|
\par Example
|
|
In the code below the function GetFirstXLightDeviceContext() comes from \ref GetFirstXLightDeviceContext "this example".
|
|
\code
|
|
#include <stdio.h>
|
|
#include "xnd.h"
|
|
|
|
void xlight_setup_example()
|
|
{
|
|
|
|
int status;
|
|
unsigned char label[XLT_LABEL_SIZE];
|
|
unsigned char password[XLT_PASSWORD_SIZE];
|
|
unsigned char dongle_key[XLT_KEY_SIZE];
|
|
unsigned char challenge_response_key[XLT_KEY_SIZE];
|
|
XND_XLT_ENV env = xnd_xlt_env_create();
|
|
XND_DEVICE_CONTEXT dev_ctx = 0;
|
|
|
|
|
|
//xnd_xlt_setup set label, password, user and challenge response keys (dongle_key and challenge_response_key) once for all.
|
|
//Only label must be specified, but it is strongly recommeded to set password, dongle_key, challenge_response_key as well
|
|
//with non trivial (random) values and keep them secret.
|
|
|
|
//BEWARE: label, password, dongle_key and challenge_response_key are not strings but arrays,
|
|
//so fill them up to their entire size
|
|
|
|
strcpy((char*)label, "My XLight label");
|
|
memset(label + strlen("My XLight label"), 0x00, sizeof(label) - strlen("My XLight label"));
|
|
|
|
//set password
|
|
...
|
|
|
|
//set dongle_key
|
|
...
|
|
|
|
//set challenge_response_key
|
|
...
|
|
|
|
//GetFirstXLightDeviceContext() comes from an example of the XNodus documentation
|
|
dev_ctx = GetFirstXLightDeviceContext(env);
|
|
if (!dev_ctx){
|
|
printf("An error occurred (probably no XLight device was found");
|
|
goto end;
|
|
}
|
|
|
|
status = xnd_xlt_setup(dev_ctx, label, password, dongle_key, challenge_response_key);
|
|
if (status != XLT_ERROR_SUCCESS){
|
|
printf("An error has occurred running xnd_xlt_setup(): error code = %d\n", status);
|
|
if (status == XLT_ERROR_INVALID_STATE){
|
|
printf("Probably the device is already programmed!\n");
|
|
}
|
|
goto end;
|
|
}
|
|
printf("XLight device correctly initialized.\n");
|
|
|
|
//...
|
|
end:
|
|
xnd_xlt_devctx_release(dev_ctx);
|
|
xnd_xlt_env_free(env);
|
|
}
|
|
\endcode
|
|
|
|
*/
|
|
XND_LINK int XND_API xnd_xlt_setup(XND_DEVICE_CONTEXT dev_ctx, const unsigned char* label, const unsigned char* password, const unsigned char* dongle_key, const unsigned char* cr_key);
|
|
|
|
/**
|
|
\ingroup xnd_xlt_bank
|
|
Write into a memory bank of the XLight device.
|
|
\param[in] dev_ctx ::XND_DEVICE_CONTEXT handle referring to the selected device.
|
|
\param[in] password points to a buffer of length ::XLT_PASSWORD_SIZE that contains the password assigned to the device.
|
|
\param[in] bank the index of the memory bank that must be written.
|
|
\param[in] data points to a buffer of size ::XLT_BANK_SIZE containing the data to be written into the memory.
|
|
\return returns ::XLT_ERROR_SUCCESS on success, an \ref xlt_Errors "error code" on failure.
|
|
\remark The <i>password</i> entry must be the same that was used in xnd_xlt_setup() call. If it was NULL, it must be NULL also in xnd_xlt_write().
|
|
|
|
\par Example
|
|
In the code below the function GetFirstXLightDeviceContext() comes from \ref GetFirstXLightDeviceContext "this example".
|
|
\code {.c}
|
|
void xlight_write_example()
|
|
{
|
|
int status;
|
|
unsigned char password[XLT_PASSWORD_SIZE];
|
|
unsigned char data[XLT_BANK_SIZE];
|
|
XND_XLT_ENV env = xnd_xlt_env_create();
|
|
XND_DEVICE_CONTEXT dev_ctx = 0;
|
|
|
|
//GetFirstXLightDeviceContext() comes from an example of the XNodus documentation
|
|
dev_ctx = GetFirstXLightDeviceContext(env);
|
|
if (!dev_ctx){
|
|
printf("An error occurred (probably no XLight device was found");
|
|
goto end;
|
|
}
|
|
|
|
//BEWARE: data, is not a not string but an array,
|
|
//so fill it up to its entire size
|
|
strcpy((char*)data, "Some data");
|
|
memset(data + strlen("Some data"), 0x00, sizeof(data) - strlen("Some data"));
|
|
|
|
//Of course you will use a more secure password than 'My XLight password' use in this example!
|
|
strcpy((char*)password, "My XLight password");
|
|
memset(password + strlen("My XLight password"), 0x00, sizeof(password) - strlen("My XLight password"));
|
|
|
|
//write in bank 0 of an XLight dongle indexed by device = 0
|
|
status = xnd_xlt_write(dev_ctx, password, 0, data);
|
|
if (status != XLT_ERROR_SUCCESS){
|
|
printf("An error has occurred.\n");
|
|
goto end;
|
|
}
|
|
//...
|
|
end:
|
|
xnd_xlt_devctx_release(dev_ctx);
|
|
xnd_xlt_env_free(env);
|
|
}
|
|
\endcode
|
|
|
|
*/
|
|
XND_LINK int XND_API xnd_xlt_write(XND_DEVICE_CONTEXT dev_ctx, const unsigned char* password, unsigned int bank, const unsigned char* data);
|
|
|
|
/**
|
|
\ingroup xnd_xlt_bank
|
|
Read from a memory bank of the XLight device.
|
|
\param[in] dev_ctx ::XND_DEVICE_CONTEXT handle referring to the selected device.
|
|
\param[in] password points to a buffer of length ::XLT_PASSWORD_SIZE that contains the password assigned to the device.
|
|
\param[in] bank the index of the memory bank that must be read.
|
|
\param[out] data points to a buffer of size ::XLT_BANK_SIZE that will receive the data read from the adressed memory bank.
|
|
\return returns ::XLT_ERROR_SUCCESS on success, an \ref xlt_Errors "error code" on failure.
|
|
\remark The <i>password</i> entry must be the same that was used in xnd_xlt_setup() call. If it was NULL, it must be NULL also in xnd_xlt_read().
|
|
|
|
\par Example
|
|
In the code below the function GetFirstXLightDeviceContext() comes from \ref GetFirstXLightDeviceContext "this example".
|
|
\code {.c}
|
|
void xlight_read_example()
|
|
{
|
|
int status;
|
|
unsigned char password[XLT_PASSWORD_SIZE];
|
|
unsigned char data[XLT_BANK_SIZE];
|
|
XND_XLT_ENV env = xnd_xlt_env_create();
|
|
XND_DEVICE_CONTEXT dev_ctx = 0;
|
|
|
|
//GetFirstXLightDeviceContext() comes from an example of the XNodus documentation
|
|
dev_ctx = GetFirstXLightDeviceContext(env);
|
|
if (!dev_ctx){
|
|
printf("An error occurred (probably no XLight device was found");
|
|
goto end;
|
|
}
|
|
|
|
strcpy((char*)password, "My XLight password");
|
|
memset(password + strlen("My XLight password"), 0x00, sizeof(password) - strlen("My XLight password"));
|
|
|
|
//read from bank 0 of an XLight dongle
|
|
status = xnd_xlt_read(dev_ctx, password, 0, data);
|
|
if (status != XLT_ERROR_SUCCESS){
|
|
printf("An error has occurred.\n");
|
|
}
|
|
else {
|
|
//N.B.: the data banks may contain not printable character
|
|
//(and in general it makes no sense print out memory content, this is just an example)
|
|
printf("Bank 0 data: %s\n", (char*)data);
|
|
}
|
|
end:
|
|
xnd_xlt_devctx_release(dev_ctx);
|
|
xnd_xlt_env_free(env);
|
|
}
|
|
\endcode
|
|
*/
|
|
XND_LINK int XND_API xnd_xlt_read(XND_DEVICE_CONTEXT dev_ctx, const unsigned char* password, unsigned int bank, unsigned char* data);
|
|
|
|
/**
|
|
\ingroup xnd_xlt_bank
|
|
Lock a memory bank.
|
|
|
|
\note <b> This function produces an irreversible setting onto the XLight device, hence use it very carefully.</b>
|
|
|
|
See \ref xn_locked_memory.
|
|
\param[in] dev_ctx ::XND_DEVICE_CONTEXT handle referring to the selected device.
|
|
\param[in] password points to a buffer of length ::XLT_PASSWORD_SIZE. It contains the password assigned to the device with xnd_xlt_setup().
|
|
\param[in] bank the index of the memory bank that must be locked.
|
|
\param[in] group_number the group number to be assigned to the locking bank.
|
|
\return returns ::XLT_ERROR_SUCCESS on success, an \ref xlt_Errors "error code" on failure.
|
|
|
|
A locked memory bank can be written only using encrypted commands created by xnd_xlt_set_write_locked_group_check() or xnd_xlt_set_write_locked_serial_check()
|
|
and performed by xnd_xlt_write_locked().
|
|
\note the group number is intended to define subgroups that must be treated in different ways. If there is no reason to create such differentiation
|
|
it must be inserted the same number for all devices, say 0.
|
|
The grouping allows to create a single encrypted command to modify the memory content of locked banks onto a large number of devices.
|
|
|
|
\remark it is not useful to set a different group number for every device because it is already possible create a command for a single device by using its serial number.
|
|
|
|
\note a locked bank can always be read using the xnd_xlt_read() function, but can't be written with xnd_xlt_write() any more.
|
|
A locked memory bank is subject to a restriction in its dimension: only ::XLT_LOCKED_BANK_DATA_LENGTH will be freely available for reading and writing.
|
|
The remaining bytes are used by the locking mechanism management.
|
|
|
|
\sa xnd_xlt_bank_lock2(), xnd_xlt_set_write_locked_group_check(), xnd_xlt_set_write_locked_serial_check()
|
|
|
|
*/
|
|
XND_LINK int XND_API xnd_xlt_bank_lock(XND_DEVICE_CONTEXT dev_ctx, const unsigned char* password, unsigned int bank, unsigned int group_number);
|
|
|
|
/**
|
|
\ingroup xnd_xlt_bank
|
|
Lock a memory bank in advanced mode (<i>Lock2</i>).
|
|
|
|
\note <b> This function produces an irreversible setting onto the XLight device, hence use it very carefully.</b>
|
|
|
|
See \ref xn_locked_memory.
|
|
\param[in] dev_ctx ::XND_DEVICE_CONTEXT handle referring to the selected device.
|
|
\param[in] password points to a buffer of length ::XLT_PASSWORD_SIZE. It contains the password assigned to the device with xnd_xlt_setup().
|
|
\param[in] bank the index of the memory bank that must be locked.
|
|
\param[in] group_number the group number to be assigned to the locking bank.
|
|
\return returns ::XLT_ERROR_SUCCESS on success, an \ref xlt_Errors "error code" on failure.
|
|
|
|
A locked2 memory bank can be written only using encrypted commands created by xnd_xlt_set_write_locked2_group_check() or xnd_xlt_set_write_locked2_serial_check()
|
|
and performed by xnd_xlt_write_locked().
|
|
\note the group number is intended to define subgroups that must be treated in different ways. If there is no reason to create such differentiation
|
|
it must be inserted the same number for all devices, say 0.
|
|
The grouping allows to create a single encrypted command to modify the memory content of locked banks onto a large number of devices.
|
|
|
|
\remark it is not useful to set a different group number for every device because it is already possible create a command for a single device by using its serial number.
|
|
|
|
\note a locked bank can always be read using the xnd_xlt_read() function, but can't be written with xnd_xlt_write() any more.
|
|
A locked2 memory bank is subject to a restriction in its dimension: only ::XLT_LOCKED_BANK_DATA_LENGTH will be freely available for reading and writing.
|
|
The remaining bytes are used by the locking mechanism management.
|
|
<p><b>Supported version</b>: this function is available on XLight devices version 1.01 or later.
|
|
\see xnd_xlt_set_write_locked2_group_check(), xnd_xlt_set_write_locked2_serial_check()
|
|
*/
|
|
XND_LINK int XND_API xnd_xlt_bank_lock2(XND_DEVICE_CONTEXT dev_ctx, const unsigned char* password, unsigned int bank, unsigned int group_number);
|
|
|
|
/**
|
|
\ingroup xnd_xlt_bank
|
|
Freeze a given memory bank. After freezing it won't be possible write inside the given bank any longer.
|
|
|
|
\note <b> This function produces an irreversible setting onto the XLight device, hence use it very carefully.</b>
|
|
|
|
\param[in] dev_ctx ::XND_DEVICE_CONTEXT handle referring to the selected device.
|
|
\param[in] password points to a buffer of length ::XLT_PASSWORD_SIZE that contains the password assigned to the device.
|
|
\param[in] bank the index of the memory bank that must be frozen.
|
|
\return returns ::XLT_ERROR_SUCCESS on success, an \ref xlt_Errors "error code" on failure.
|
|
\remark The <i>password</i> entry must be the same that was used in xnd_xlt_setup() call. If it was NULL, it must be NULL also in xnd_xlt_bank_freeze().
|
|
|
|
\par Example
|
|
In the code below the function GetFirstXLightDeviceContext() comes from \ref GetFirstXLightDeviceContext "this example".
|
|
\code{.c}
|
|
void xlight_freeze_example()
|
|
{
|
|
int status;
|
|
unsigned char password[XLT_PASSWORD_SIZE];
|
|
XND_XLT_ENV env = xnd_xlt_env_create();
|
|
XND_DEVICE_CONTEXT dev_ctx = 0;
|
|
|
|
//GetFirstXLightDeviceContext() comes from an example of the XNodus documentation
|
|
dev_ctx = GetFirstXLightDeviceContext(env);
|
|
if (!dev_ctx){
|
|
printf("An error occurred (probably no XLight device was found");
|
|
goto end;
|
|
}
|
|
|
|
strcpy((char*)password, "My XLight password");
|
|
memset(password + strlen("My XLight password"), 0x00, sizeof(password) - strlen("My XLight password"));
|
|
|
|
//freeze the bank 0 of an XLight dongle
|
|
//BEWARE: after the freeze the memory content of the bank 0 can't be modified any longer
|
|
status = xnd_xlt_bank_freeze(dev_ctx, password, 0);
|
|
if (status != XLT_ERROR_SUCCESS){
|
|
printf("An error has occurred.\n");
|
|
if (status == XLT_ERROR_FROZEN){
|
|
printf("The device was already frozen.\n");
|
|
}
|
|
}
|
|
|
|
end:
|
|
xnd_xlt_devctx_release(dev_ctx);
|
|
xnd_xlt_env_free(env);
|
|
}
|
|
\endcode
|
|
|
|
*/
|
|
XND_LINK int XND_API xnd_xlt_bank_freeze(XND_DEVICE_CONTEXT dev_ctx, const unsigned char* password, unsigned int bank);
|
|
|
|
/**
|
|
\deprecated
|
|
This function is deprecated because substituted by the more effective \ref xn_AES_Session_Key "session encryption".
|
|
|
|
Perform AES-256 encryption
|
|
\param[in] dev_ctx ::XND_DEVICE_CONTEXT handle referring to the selected device.
|
|
\param[in] plaintext points to the buffer of length ::XLT_CIPHERTEXT_SIZE containing the plaintext to encrypt.
|
|
\param[out] ciphertext points to the buffer of length ::XLT_CIPHERTEXT_SIZE receiving the encrypted result.
|
|
\return returns ::XLT_ERROR_SUCCESS on success, an \ref xlt_Errors "error code" on failure.
|
|
\note The encryption function uses as cryptographic key the <i>Dongle Key</i> entry set by xnd_xlt_setup().
|
|
\note We strongly recommend never to put <i>Dongle Key</i> in the protected application. Use <i>Dongle Key</i> to encrypt data, but not
|
|
for authentication processes as discussed in xnd_xlt_challenge() documentation.
|
|
*/
|
|
XND_LINK int XND_API xnd_xlt_encrypt(XND_DEVICE_CONTEXT dev_ctx, const unsigned char* plaintext, unsigned char* ciphertext);
|
|
|
|
/**
|
|
\deprecated
|
|
This function is deprecated because substituted by the more effective \ref xn_AES_Session_Key "session encryption".
|
|
|
|
Perform AES-256 decryption.
|
|
\param[in] dev_ctx ::XND_DEVICE_CONTEXT handle referring to the selected device.
|
|
\param[in] ciphertext points to the buffer of length ::XLT_CIPHERTEXT_SIZE containing the ciphertext to be decrypted.
|
|
\param[out] plaintext points to the buffer of length ::XLT_CIPHERTEXT_SIZE containing the result of the decryption.
|
|
\return returns ::XLT_ERROR_SUCCESS on success, an \ref xlt_Errors "error code" on failure.
|
|
\remark This function is the inverse of xnd_xlt_encrypt(), that is from ciphertext it returns the original plaintext passed to xnd_xlt_encrypt().
|
|
\note The decryption function uses as cryptographic key the <i>Dongle Key</i> entry set by xnd_xlt_setup().
|
|
*/
|
|
XND_LINK int XND_API xnd_xlt_decrypt(XND_DEVICE_CONTEXT dev_ctx, const unsigned char* ciphertext, unsigned char* plaintext);
|
|
|
|
/**
|
|
\deprecated
|
|
This function is deprecated because substituted by the more effective \ref xn_AES_Session_Key "session encryption".
|
|
|
|
Challenge-Response computation based on AES-256.
|
|
The protected software send a value and check that the outcome is as expected.
|
|
\param[in] dev_ctx ::XND_DEVICE_CONTEXT handle referring to the selected device.
|
|
\param[in] challenge points to the buffer of length ::XLT_CIPHERTEXT_SIZE containing the challenge data.
|
|
\param[out] response points to the buffer of length ::XLT_CIPHERTEXT_SIZE receiving the response.
|
|
\return returns ::XLT_ERROR_SUCCESS on success, an \ref xlt_Errors "error code" on failure.
|
|
\note The Challenge-Response mechanism uses as cryptographic key the <i>cr_key</i> (<i>Challenge Response Key</i>) entry set by xnd_xlt_setup().
|
|
\remark The challenge response mechanism is a sort of proof of identity without exposing details to eavesdroppers on the USB communication or
|
|
on the dll interface. It is based onto the AES-256 encryption and the verifier inside the protected program must know the key used by the
|
|
device. A good hacker debugging the code can come up to the encryption key, so the best policy is to make this task hard trying to hide
|
|
the key: for instance preparing the challenge and evaluating the response far from the code communicating with the dongle. The example below is not a good
|
|
example from this point of view and it must be considered just as an example. xnd_xlt_challenge() works in the same way of xnd_xlt_encrypt() but using a different AES key.
|
|
|
|
\note Another possible and better way is to calculate many pairs challenge-presponse in a safe environment (i.e. not in the protected application)
|
|
and use such pairs to verify the response of the dongle. This method avoid the exposure of the <i>Challenge Response Key</i>.
|
|
*/
|
|
XND_LINK int XND_API xnd_xlt_challenge(XND_DEVICE_CONTEXT dev_ctx, const unsigned char* challenge, unsigned char* response);
|
|
|
|
/**
|
|
\ingroup xnd_xlt_aes
|
|
Load on an XLight device the session AES key to be used for AES session encryption functions.
|
|
See \ref xn_AES_Session_Key for an introduction on <i>Session Key</i> protection.
|
|
|
|
\param[in] dev_ctx ::XND_DEVICE_CONTEXT handle referring to the selected device.
|
|
\param[in] key_index index of the key to be used. This value runs from 0 to ::XLT_SESSION_NUMBER_OF_KEYS -1.
|
|
\param[in] wrapped_key points to the buffer of length ::XLT_KEY_SIZE containing the <i>Session Key</i> encrypted with <i>Dongle Key</i>.
|
|
\return returns ::XLT_ERROR_SUCCESS on success, an \ref xlt_Errors "error code" on failure.
|
|
|
|
This function must be used to set the AES key that will be used by xnd_xlt_session_encrypt() and xnd_xlt_session_decrypt(). This cryptographic key
|
|
must be passed in encrypted (wrapped) form depending on the <i>Dongle Key<i>. In oreder to produce the wrapped form of the <i>Session Key</i> use xnd_xlt_session_wrap_key().
|
|
It is possible to set ::XLT_SESSION_NUMBER_OF_KEYS sessin key simultaneously, with key_index it is possible to refer to one of these keys.
|
|
|
|
\note a <i>Session Key</i> is not permanent, it resides on the device as long as the dongle is plugged and powered, once the dongle is
|
|
removed the key is deleted. This means that it must be loaded every time it must be used. The default value, that is just after the device is plugged,
|
|
is a zero buffer.
|
|
See \ref xn_Session_KeyProtection "here" for a source code example using this function.
|
|
<p><b>Supported version</b>: this function is available on XLight devices version 2.0 or later.
|
|
\see xnd_xlt_session_encrypt(), xnd_xlt_session_decrypt(), xnd_xlt_session_wrap_key().
|
|
*/
|
|
XND_LINK int XND_API xnd_xlt_session_set_key(XND_DEVICE_CONTEXT dev_ctx, unsigned int key_index, const unsigned char* wrapped_key);
|
|
|
|
/**
|
|
\ingroup xnd_xlt_aes
|
|
Encrypt data using a <i>Session Key</i>.
|
|
See \ref xn_AES_Session_Key for an introduction on <i>Session Key</i> protection.
|
|
\param[in] dev_ctx ::XND_DEVICE_CONTEXT handle referring to the selected device.
|
|
\param[in] key_index index of the key to be used. This value runs from 0 to ::XLT_SESSION_NUMBER_OF_KEYS -1.
|
|
\param[in] plaintext points to the buffer of length ::XLT_CIPHERTEXT_SIZE containing the data to be encrypted
|
|
\param[out] ciphertext points to the buffer of length ::XLT_CIPHERTEXT_SIZE that will receive the encrypted data.
|
|
\return returns ::XLT_ERROR_SUCCESS on success, an \ref xlt_Errors "error code" on failure.
|
|
|
|
This function performs AES-256 encryption of a plaintext of length ::XLT_CIPHERTEXT_SIZE and inserts the ciphertext result in a buffer of the same length.
|
|
The AES key is one of the eight <i>Session Keys</i> specified by the index <i>key_index</i>, and the corrisponding key was previously set by the xnd_xlt_session_decrypt() function.
|
|
|
|
See \ref xn_Session_KeyProtection "here" for a source code example using this function.
|
|
<p><b>Supported version</b>: this function is available on XLight devices version 2.0 or later.
|
|
\see xnd_xlt_session_decrypt(), xnd_xlt_session_set_key(), xnd_xlt_session_wrap_key().
|
|
*/
|
|
XND_LINK int XND_API xnd_xlt_session_encrypt(XND_DEVICE_CONTEXT dev_ctx, unsigned int key_index, const unsigned char* plaintext, unsigned char* ciphertext);
|
|
|
|
/**
|
|
\ingroup xnd_xlt_aes
|
|
Decrypt data using a <i>Session Key</i>.
|
|
See \ref xn_AES_Session_Key for an introduction on <i>Session Key</i> protection.
|
|
\param[in] dev_ctx ::XND_DEVICE_CONTEXT handle referring to the selected device.
|
|
\param[in] key_index index of the key to be used. This value runs from 0 to ::XLT_SESSION_NUMBER_OF_KEYS -1.
|
|
\param[in] ciphertext points to the buffer of length ::XLT_CIPHERTEXT_SIZE containing the data to be decrypted.
|
|
\param[out] plaintext points to the buffer of length ::XLT_CIPHERTEXT_SIZE that will receive the decrypted data.
|
|
\return returns ::XLT_ERROR_SUCCESS on success, an \ref xlt_Errors "error code" on failure.
|
|
|
|
This function performs AES-256 decryption of a ciphertext buffer with length of the block of the AES algorithm, that is a length of ::XLT_CIPHERTEXT_SIZE.
|
|
The used key was set by a previous call of xnd_xlt_session_set_key().
|
|
<p><b>Supported version</b>: this function is available on XLight devices version 2.0 or later.
|
|
\see xnd_xlt_session_encrypt(), xnd_xlt_session_set_key(), xnd_xlt_session_wrap_key().
|
|
*/
|
|
XND_LINK int XND_API xnd_xlt_session_decrypt(XND_DEVICE_CONTEXT dev_ctx, unsigned int key_index, const unsigned char* ciphertext, unsigned char* plaintext);
|
|
|
|
/**
|
|
\ingroup xnd_xlt_aes
|
|
Wraps a <i>Session Key</i>.
|
|
See \ref xn_AES_Session_Key for an introduction on <i>Session Key</i> protection.
|
|
\param[in] dev_ctx ::XND_DEVICE_CONTEXT handle referring to a real or fake device.
|
|
\param[in] key points to the AES key that will be used by xnd_xlt_session_encrypt() and xnd_xlt_session_decrypt(). It's length is of ::XLT_KEY_SIZE bytes.
|
|
\param[in] dongle_key points to the value of the <i>Dongle Key</i> set up by xnd_xlt_setup() function.
|
|
\param[out] wrapped_key points to a memory buffer of length ::XLT_KEY_SIZE that will receive the wrapped version of key.
|
|
\return returns ::XLT_ERROR_SUCCESS on success, an \ref xlt_Errors "error code" on failure.
|
|
|
|
\note Never use this function onto the protected software, in particular, never insert the <i>Dongle Key</i> into the protected software.
|
|
This is an utility software to compute the wrapped version of a <i>Session Key</i> and must be done in an utility software not distributed to the
|
|
final user. The <i>Wrapped Key</i> must be used onto the protected software and loaded onto the XLight dongle using xnd_xlt_session_set_key().
|
|
|
|
See \ref xn_Session_KeyPreliminary "here" for a source code example using this function.
|
|
|
|
<p><b>Supported version</b>: this function is available on XLight devices version 2.0 or later.
|
|
|
|
\sa xnd_xlt_session_set_key().
|
|
*/
|
|
XND_LINK int XND_API xnd_xlt_session_wrap_key(XND_DEVICE_CONTEXT dev_ctx, const unsigned char* key, const unsigned char* dongle_key, unsigned char* wrapped_key);
|
|
|
|
/**
|
|
\ingroup xnd_xlt_rsa
|
|
Generate an RSA key.
|
|
See \ref xn_RSA_Protection for an introduction on the RSA protection in XLight.
|
|
\param[in] dev_ctx ::XND_DEVICE_CONTEXT handle referring to a real or fake device.
|
|
\param[in] bit_size the length in bit of the key to generate. The possible values are ::XLT_RSA_512_BIT_SIZE and ::XLT_RSA_1024_BIT_SIZE.
|
|
\param[out] private_key points to the buffer that will receive the generated RSA private key formatted with XLight RSA Key format (\ref xn_RSA_format).
|
|
\param[in] private_key_size size of the private_key buffer. The size for a 1024 bit key is ::XLT_RSA_1024_PRIV_KEY_SIZE and the size for a 512 bit key is ::XLT_RSA_512_PRIV_KEY_SIZE.
|
|
\param[out] p_private_key_len points to an unsigned integer that will receive the actual length of the generated formatted private key.
|
|
\param[out] public_key points to the buffer that will receive the generated RSA public key formatted in XLight RSA Key format (\ref xn_RSA_format).
|
|
If this parameter is NULL the public key is not retrieved.
|
|
\param[in] public_key_size size of the public_key buffer. The size for a 1024 bit key is ::XLT_RSA_1024_PUB_KEY_SIZE and the size for a 512 bit key is ::XLT_RSA_512_PUB_KEY_SIZE.
|
|
\param[out] p_public_key_len points to an unsigned integer that will receive the actual length of the generated formatted public key.
|
|
\return ::XLT_ERROR_SUCCESS on success, an \ref xlt_Errors "error code" on failure.
|
|
|
|
\note This is an utility function that must be never used onto the protected software. Its purpose is RSA key generation and may be substituted
|
|
by other software doing the same task. There are plenty of source code available in internet doing RSA key generation.
|
|
<p><b>Supported version</b>: this function is available on XLight devices version 2.0 or later.
|
|
\sa xnd_xlt_rsa_wrap_privkey().
|
|
*/
|
|
XND_LINK int XND_API xnd_xlt_rsa_generate_key(XND_DEVICE_CONTEXT dev_ctx, unsigned int bit_size, unsigned char* private_key, unsigned int private_key_size, unsigned int* p_private_key_len, unsigned char* public_key, unsigned int public_key_size, unsigned int* p_public_key_len);
|
|
|
|
/**
|
|
\ingroup xnd_xlt_rsa
|
|
Wraps an RSA key.
|
|
See \ref xn_RSA_Protection for an introduction on the RSA protection in XLight.
|
|
\param[in] dev_ctx ::XND_DEVICE_CONTEXT handle referring to a real or fake device.
|
|
\param[in] private_key points to a buffer containing a formatted private key.
|
|
\param[in] private_key_length length of the RSA formatted key (\ref xn_RSA_format).
|
|
\param[in] dongle_key points to a buffer containing <i>Dongle Key</i>.
|
|
\param[out] wrapped_key points to the buffer that will receive an encryption of the RSA private key (wrapped).
|
|
\param[in] wrapped_key_len the length of <i>Wrapped Key</i> pointed by wrapped_key. The length of a <i>Wrapped Key</i> must be ::XLT_RSA_1024_WRAPPED_KEY_SIZE for a 1024-bit key and ::XLT_RSA_512_WRAPPED_KEY_SIZE for a 512-bit key.
|
|
\return ::XLT_ERROR_SUCCESS on success, an \ref xlt_Errors "error code" on failure.
|
|
|
|
\note This is an utility function that must be never used onto the protected software. Its purpose is to encrypt an RSA private key for protecting its
|
|
content. The produced <i>Wrapped Key</i> may reside into a protected software or exposed to the public access without revealing its real content.
|
|
In order to insert a private key onto the device the <i>Wrapped Key</i> must be passed to the function xnd_xlt_rsa_set_privkey().
|
|
\sa xnd_xlt_rsa_set_privkey()
|
|
*/
|
|
XND_LINK int XND_API xnd_xlt_rsa_wrap_privkey(XND_DEVICE_CONTEXT dev_ctx, const unsigned char* private_key, unsigned int private_key_length, const unsigned char* dongle_key, unsigned char* wrapped_key, unsigned int wrapped_key_len);
|
|
|
|
/**
|
|
\ingroup xnd_xlt_rsa
|
|
Wraps an RSA key.
|
|
As xnd_xlt_rsa_wrap_privkey() function but with the addition to bind a specific recipient XLight device by its serial number.
|
|
See \ref xn_RSA_Protection for an introduction on the RSA protection in XLight.
|
|
\param[in] dev_ctx ::XND_DEVICE_CONTEXT handle referring to a real or fake device.
|
|
\param[in] private_key points to a buffer containing a formatted private key.
|
|
\param[in] private_key_length length of the RSA formatted key (\ref xn_RSA_format).
|
|
\param[in] dongle_key points to a buffer containing <i>Dongle Key</i>.
|
|
\param[in] sn the serial number of the destination XLight device.
|
|
\param[out] wrapped_key points to the buffer that will receive an encryption of the RSA private key (wrapped).
|
|
\param[in] wrapped_key_len the length of <i>Wrapped Key</i> pointed by wrapped_key. The length of a <i>Wrapped Key</i> must be ::XLT_RSA_1024_WRAPPED_KEY_SIZE for a 1024-bit key and ::XLT_RSA_512_WRAPPED_KEY_SIZE for a 512-bit key.
|
|
\return ::XLT_ERROR_SUCCESS on success, an \ref xlt_Errors "error code" on failure.
|
|
|
|
\note This is an utility function that must be never used onto the protected software. Its purpose is to encrypt an RSA private key for protecting its
|
|
content. The produced <i>Wrapped Key</i> may reside into a protected software or exposed to the public access without revealing its real content.
|
|
In order to insert a private key onto the device the <i>Wrapped Key</i> must be passed to the function xnd_xlt_rsa_set_privkey().
|
|
|
|
<p><b>Supported version</b>: this function is available on XLight devices version 2.4 or later.
|
|
\sa xnd_xlt_rsa_wrap_privkey()
|
|
*/
|
|
XND_LINK int XND_API xnd_xlt_rsa_wrap_privkey_sn(XND_DEVICE_CONTEXT dev_ctx, const unsigned char* private_key, unsigned int private_key_length, const unsigned char* dongle_key, unsigned int sn, unsigned char* wrapped_key, unsigned int wrapped_key_len);
|
|
|
|
/**
|
|
\ingroup xnd_xlt_rsa
|
|
Load an RSA private key onto an XLight device.
|
|
See \ref xn_RSA_Protection for an introduction on the RSA protection in XLight.
|
|
\param[in] dev_ctx ::XND_DEVICE_CONTEXT handle referring to the selected device.
|
|
\param[in] wrapped_key points to the buffer containing the wrapped RSA key to be inserted into ther XLight device.
|
|
\param[in] wrapped_key_length the length of the <i>Wrapped Key</i> data.
|
|
\return ::XLT_ERROR_SUCCESS on success, an \ref xlt_Errors "error code" on failure.
|
|
|
|
\note on an XLight device it is possible to store two RSA keys: one 1024 bit key and one 512 bit key. The bit length reppresent the length of its
|
|
"modulus", not the length of the data containing the key (see \ref RSA_format). The device recognizes the two different key types and write them in their reserved memory place.
|
|
|
|
The RSA key received from this function is not in clear form, but encrypted by the function xnd_xlt_rsa_wrap_privkey().
|
|
In this way the RSA private key can be set by the protected program without exposing any relevant data, and hence preventing a hacker to understand the values (which would ruin all the security protocol based on RSA).
|
|
|
|
\note an RSA key is present onto the device also after device removal because it is written in a non volatile memory,
|
|
nevertheless it can be always overwritten with a new one.
|
|
<p><b>Supported version</b>: this function is available on XLight devices version 2.0 or later.
|
|
\see xnd_xlt_rsa_wrap_privkey().
|
|
*/
|
|
XND_LINK int XND_API xnd_xlt_rsa_set_privkey(XND_DEVICE_CONTEXT dev_ctx, const unsigned char* wrapped_key, unsigned int wrapped_key_length);
|
|
|
|
/**
|
|
\ingroup xnd_xlt_rsa
|
|
Performs RSA encryption.
|
|
\deprecated just use for test purpose
|
|
|
|
See \ref xn_RSA_Protection for an introduction on the RSA protection in XLight.
|
|
\param[in] dev_ctx ::XND_DEVICE_CONTEXT handle referring to a real or fake device.
|
|
\param[in] public_key points to the buffer containing the formatted public key used for the encryption.
|
|
\param[in] public_key_len length of the formatted public key. The allowed values are ::XLT_RSA_1024_PUB_KEY_SIZE and ::XLT_RSA_512_PUB_KEY_SIZE.
|
|
\param[in] plaintext points to the buffer containing the data to be encrypted.
|
|
\param[in] plaintext_ciphertext_length the length of plaintext and the size of the buffer pointed by ciphertext.
|
|
The allowed values for this argument are ::XLT_RSA_1024_PLAINTEXT_SIZE and ::XLT_RSA_512_PLAINTEXT_SIZE, if the plaintext is shorter it must be
|
|
copied into a buffer of the proper length and zero padded up to its overall length.
|
|
\param[out] ciphertext points to the buffer that will receive the result of the encryption.
|
|
\return ::XLT_ERROR_SUCCESS on success, an \ref xlt_Errors "error code" on failure.
|
|
\note This function is present for test purpose, never use it in the application protected with XLight.
|
|
*/
|
|
XND_LINK int XND_API xnd_xlt_never_use_this_rsa_encrypt(XND_DEVICE_CONTEXT dev_ctx, const unsigned char* public_key, unsigned int public_key_len, const unsigned char* plaintext, unsigned int plaintext_ciphertext_length, unsigned char* ciphertext);
|
|
|
|
/**
|
|
\ingroup xnd_xlt_rsa
|
|
Performs a software RSA decryption.
|
|
\deprecated just use for test purpose
|
|
|
|
See \ref xn_RSA_Protection for an introduction on the RSA protection in XLight.
|
|
\param[in] dev_ctx ::XND_DEVICE_CONTEXT handle referring to a real or fake device.
|
|
\param[in] private_key points to a buffer containing the formatted private RSA key to be used.
|
|
\param[in] private_key_len length of the formatted private key. The allowed values are ::XLT_RSA_1024_PRIV_KEY_SIZE and ::XLT_RSA_512_PRIV_KEY_SIZE.
|
|
\param[in] ciphertext points to the buffer containing the data to be decrypted.
|
|
\param[in] ciphertext_plaintext_length the length of the data to be decrypted, and the size of the receiving buffer.
|
|
The allowed values for this argument are ::XLT_RSA_1024_PLAINTEXT_SIZE and ::XLT_RSA_512_PLAINTEXT_SIZE, if the plaintext is shorter it must be
|
|
copied into a buffer of the proper length and zero padded up to its overall length.
|
|
\param[out] plaintext points to the buffer that will receive the result of the decryption.
|
|
\return ::XLT_ERROR_SUCCESS on success, an \ref xlt_Errors "error code" on failure.
|
|
*/
|
|
XND_LINK int XND_API xnd_xlt_never_use_this_rsa_sw_decrypt(XND_DEVICE_CONTEXT dev_ctx, const unsigned char* private_key, unsigned int private_key_len, const unsigned char* ciphertext, unsigned int ciphertext_plaintext_length, unsigned char* plaintext);
|
|
|
|
/**
|
|
\ingroup xnd_xlt_rsa
|
|
Runs an RSA decryption onto an XLight device.
|
|
See \ref xn_RSA_Protection for an introduction on the RSA protection in XLight.
|
|
\param[in] dev_ctx ::XND_DEVICE_CONTEXT handle referring to the selected device.
|
|
\param[in] ciphertext points to the buffer containing the data to be decrypted.
|
|
\param[in] ciphertext_plaintext_length the length of the data to be decrypted, and the size of the receiving buffer.
|
|
The allowed values for this argument are ::XLT_RSA_1024_PLAINTEXT_SIZE and ::XLT_RSA_512_PLAINTEXT_SIZE, if the plaintext is shorter it must be
|
|
copied into a buffer of the proper length and zero padded up to its overall length (see \ref xn_RSA_format).
|
|
\param[out] plaintext points to the buffer that will receive the result of the decryption.
|
|
\return ::XLT_ERROR_SUCCESS on success, an \ref xlt_Errors "error code" on failure.
|
|
\note The length of the ciphertext buffer must be the same of the plaintext. If the length is ::XLT_RSA_1024_PLAINTEXT_SIZE the 1024-bit key is used,
|
|
if the length is ::XLT_RSA_512_PLAINTEXT_SIZE the 512-bit key is used, for any other value an error is returned.
|
|
<p><b>Supported version</b>: this function is available on XLight devices version 2.0 or later.
|
|
*/
|
|
XND_LINK int XND_API xnd_xlt_rsa_decrypt(XND_DEVICE_CONTEXT dev_ctx, const unsigned char* ciphertext, unsigned int ciphertext_plaintext_length, unsigned char* plaintext);
|
|
|
|
/**
|
|
\ingroup xnd_xlt_bank
|
|
Perform a write operation in a locked bank (both normal and advanced <i>Lock2</i> mode).
|
|
|
|
See \ref xn_locked_memory.
|
|
\param[in] dev_ctx ::XND_DEVICE_CONTEXT handle referring to the selected device.
|
|
\param[in] bank the index of the memory bank that must be written.
|
|
\param[in] data points to a buffer of size ::XLT_LOCKED_TRANSFER_DATA containing the values computed by xnd_xlt_set_write_locked_serial_check() or
|
|
xlt_set_write_locked_group_check().
|
|
\return returns ::XLT_ERROR_SUCCESS on success, an \ref xlt_Errors "error code" on failure.
|
|
\sa xnd_xlt_set_write_locked2_serial_check(), xnd_xlt_set_write_locked2_group_check().
|
|
*/
|
|
XND_LINK int XND_API xnd_xlt_write_locked(XND_DEVICE_CONTEXT dev_ctx, unsigned int bank, const unsigned char* data);
|
|
|
|
/**
|
|
\ingroup xnd_xlt_bank
|
|
Perform a read operation in a locked bank (both normal and advanced <i>Lock2</i> mode).
|
|
|
|
See \ref xn_locked_memory.
|
|
\param[in] dev_ctx ::XND_DEVICE_CONTEXT handle referring to the selected device.
|
|
\param[in] bank the index of the memory bank that must be read.
|
|
\param[out] data points to a buffer of size ::XLT_LOCKED_TRANSFER_DATA that will receive the content of the memory bank in encrypted form.
|
|
\return returns ::XLT_ERROR_SUCCESS on success, an \ref xlt_Errors "error code" on failure.
|
|
\remark in order to get the data in plain form the function xnd_xlt_decrypt_locked2_data() must be used.
|
|
\note a locked bank can always be read using the xnd_xlt_read() function, while this function doesn't need the use
|
|
of <i>password</i>, but its outcome can't be used as is, because it needs decryption.
|
|
|
|
A locked memory bank is subjected to a restriction in its dimension: only ::XLT_LOCKED_BANK_DATA_LENGTH will be freely available for reading and writing.
|
|
The remaining bytes are used by the locking mechanism management.
|
|
\sa xnd_xlt_decrypt_locked2_data().
|
|
*/
|
|
XND_LINK int XND_API xnd_xlt_read_locked(XND_DEVICE_CONTEXT dev_ctx, unsigned int bank, unsigned char* data);
|
|
|
|
/**
|
|
\ingroup xnd_xlt_bank
|
|
Encrypt the buffer to be written into a locked bank of a specific XLight device.
|
|
This data can be written only once and only in the device with a given serial number, provided that the destination bank is locked (see xnd_xlt_bank_lock2()).
|
|
|
|
See \ref xn_locked_memory.
|
|
\param[in] dev_ctx ::XND_DEVICE_CONTEXT handle referring to a real or fake device.
|
|
\param[in] data points to a buffer of length ::XLT_LOCKED_BANK_DATA_LENGTH, that contains the value that must be written onto a locked bank.
|
|
\param[in] bank specify the index of the memory bank that must written.
|
|
\param[in] new_counter new counter value: this value must be greater than the counter value currently contained into the locked bank.
|
|
\param[in] serial the serial number of the XLight device target.
|
|
\param[in] dongle_key points to a buffer of length ::XLT_KEY_SIZE. It contains the AES-256 key <i>Dongle Key</i> set during xnd_xlt_getinfo() call.
|
|
\param[out] encryted_data points to a buffer of size ::XLT_LOCKED_TRANSFER_DATA that will receive the encrypted write command that will be
|
|
applied onto the XLight device via the xnd_xlt_write_locked() function.
|
|
to the XLight device with the xnd_xlt_write() function in order to write <i>data</i> into a locked bank.
|
|
\return returns ::XLT_ERROR_SUCCESS on success, an \ref xlt_Errors "error code" on failure.
|
|
|
|
\remark This function is to be considered as an utility not to be used diretly by the protected software.
|
|
It can be used by the vendor of the protected software in order to remotely update the locked memory of a device.
|
|
In this scenario the <i>Dongle Key</i> key must never be used onto the protected software, but used only to generate update for the device memory.
|
|
This way it is possible to remotely update the content of a locked bank. A locked bank can be read normally by a protected application using xnd_xlt_read(), so
|
|
this remote update technique can be used, for instance, for license management purposes.
|
|
\sa xnd_xlt_set_write_locked_group_check(), xnd_xlt_write_locked(), xnd_xlt_read_locked(), xnd_xlt_decrypt_locked_data().
|
|
*/
|
|
XND_LINK int XND_API xnd_xlt_set_write_locked_serial_check(XND_DEVICE_CONTEXT dev_ctx, const unsigned char* data, unsigned int bank, unsigned int new_counter, unsigned int serial, const unsigned char* dongle_key , unsigned char* encryted_data);
|
|
|
|
/**
|
|
\ingroup xnd_xlt_bank
|
|
Encrypt the buffer to be written into a locked bank belonging to an XLight devices of a given group.
|
|
This data can be written only once provided that the destination bank is locked (see xnd_xlt_bank_lock()).
|
|
|
|
See \ref xn_locked_memory.
|
|
\param[in] dev_ctx ::XND_DEVICE_CONTEXT handle referring to a real or fake device.
|
|
\param[in] data points to a buffer of length ::XLT_LOCKED_BANK_DATA_LENGTH, that contains the value that must be written into the locked bank.
|
|
\param[in] bank specify the index of the memory bank that must written.
|
|
\param[in] new_counter new counter value: this value must be greater than the counter value currently contained into the locked bank.
|
|
\param[in] group_number the group number of the XLight devices for which the encrypted buffer is prepared.
|
|
\param[in] dongle_key points to a buffer of length ::XLT_KEY_SIZE. It contains the AES-256 key <i>Dongle Key</i> set during xnd_xlt_getinfo() call.
|
|
\param[out] encryted_data points to a buffer of size ::XLT_LOCKED_TRANSFER_DATA that will receive the encrypted write command that will be
|
|
applied onto the XLight device via the xnd_xlt_write_locked() function.
|
|
\return returns ::XLT_ERROR_SUCCESS on success, an \ref xlt_Errors "error code" on failure.
|
|
|
|
\remark The group number correspond to what is set on the dongle by xnd_xlt_bank_lock().
|
|
It is intended to define subgroups of devices each of them must be treated in the same way.
|
|
For further notices see the comments of xnd_xlt_set_write_locked_serial_check(), they hold also for this function.
|
|
*/
|
|
XND_LINK int XND_API xnd_xlt_set_write_locked_group_check(XND_DEVICE_CONTEXT dev_ctx, const unsigned char* data, unsigned int bank, unsigned int new_counter, unsigned int group_number, const unsigned char* dongle_key, unsigned char* encryted_data);
|
|
|
|
/**
|
|
\ingroup xnd_xlt_bank
|
|
Encrypt the buffer to be written into a bank locked with <i>Lock2</i> of a specific XLight device.
|
|
This data can be written only once and only in the device with a given serial number, provided that the destination bank is locked (see xnd_xlt_bank_lock2()).
|
|
|
|
See \ref xn_locked_memory.
|
|
\param[in] dev_ctx ::XND_DEVICE_CONTEXT handle referring to a real or fake device.
|
|
\param[in] data points to a buffer of length ::XLT_LOCKED_BANK_DATA_LENGTH, that contains the value that must be written onto a locked bank.
|
|
\param[in] bank specify the index of the memory bank that must written.
|
|
\param[in] new_counter new counter value: this value must be greater than the counter value currently contained into the locked bank.
|
|
\param[in] serial the serial number of the XLight device target.
|
|
\param[in] dongle_key points to a buffer of length ::XLT_KEY_SIZE. It contains the AES-256 key <i>Dongle Key</i> set during xnd_xlt_getinfo() call.
|
|
\param[out] encryted_data points to a buffer of size ::XLT_LOCKED_TRANSFER_DATA that will receive the encrypted write command that will be
|
|
applied onto the XLight device via the xnd_xlt_write_locked() function.
|
|
to the XLight device with the xnd_xlt_write() function in order to write <i>data</i> into a locked bank.
|
|
\return returns ::XLT_ERROR_SUCCESS on success, an \ref xlt_Errors "error code" on failure.
|
|
|
|
\remark This function is to be considered as an utility not to be used diretly by the protected software.
|
|
It can be used by the vendor of the protected software in order to remotely update the locked memory of a device.
|
|
In this scenario the <i>Dongle Key</i> key must never be used onto the protected software, but used only to generate update for the device memory.
|
|
This way it is possible to remotely update the content of a locked bank. A locked bank can be read normally by a protected application using xnd_xlt_read(), so
|
|
this remote update technique can be used, for instance, for license management purposes.
|
|
<p><b>Supported version</b>: this function is available on XLight devices version 1.01 or later.
|
|
\see xnd_xlt_set_write_locked2_group_check(), xnd_xlt_write_locked(), xnd_xlt_read_locked(), xnd_xlt_decrypt_locked2_data().
|
|
*/
|
|
XND_LINK int XND_API xnd_xlt_set_write_locked2_serial_check(XND_DEVICE_CONTEXT dev_ctx, const unsigned char* data, unsigned int bank, unsigned int new_counter, unsigned int serial, const unsigned char* dongle_key , unsigned char* encryted_data);
|
|
|
|
/**
|
|
\ingroup xnd_xlt_bank
|
|
Encrypt the buffer to be written into a bank locked with <i>Lock2</i> belonging to an XLight devices of a given group.
|
|
This data can be written only once provided that the destination bank is locked (see xnd_xlt_bank_lock2()).
|
|
|
|
See \ref xn_locked_memory.
|
|
\param[in] dev_ctx ::XND_DEVICE_CONTEXT handle referring to a real or fake device.
|
|
\param[in] data points to a buffer of length ::XLT_LOCKED_BANK_DATA_LENGTH, that contains the value that must be written into the locked bank.
|
|
\param[in] bank specify the index of the memory bank that must written.
|
|
\param[in] new_counter new counter value: this value must be greater than the counter value currently contained into the locked bank.
|
|
\param[in] group_number the group number of the XLight devices for which the encrypted buffer is prepared.
|
|
\param[in] dongle_key points to a buffer of length ::XLT_KEY_SIZE. It contains the AES-256 key <i>Dongle Key</i> set during xnd_xlt_getinfo() call.
|
|
\param[out] encryted_data points to a buffer of size ::XLT_LOCKED_TRANSFER_DATA that will receive the encrypted write command that will be
|
|
applied onto the XLight device via the xnd_xlt_write_locked() function.
|
|
\return returns ::XLT_ERROR_SUCCESS on success, an \ref xlt_Errors "error code" on failure.
|
|
|
|
\remark The group number correspond to what is set on the dongle by xnd_xlt_bank_lock2().
|
|
It is intended to define subgroups of devices each of them must be treated in the same way.
|
|
For further notices see the comments of xnd_xlt_set_write_locked_serial_check(), they hold also for this function.
|
|
<p><b>Supported version</b>: this function is available on XLight devices version 1.01 or later.
|
|
*/
|
|
XND_LINK int XND_API xnd_xlt_set_write_locked2_group_check(XND_DEVICE_CONTEXT dev_ctx, const unsigned char* data, unsigned int bank, unsigned int new_counter, unsigned int group_number, const unsigned char* dongle_key, unsigned char* encryted_data);
|
|
|
|
/**
|
|
\ingroup xnd_xlt_bank
|
|
Retrieve the data in clear form of the content of a locked memory bank.
|
|
|
|
See \ref xn_locked_memory.
|
|
\param[in] dev_ctx ::XND_DEVICE_CONTEXT handle referring to a real or fake device.
|
|
\param[in] encrypted_data points to a buffer of length ::XLT_LOCKED_TRANSFER_DATA.
|
|
\param[in] dongle_key points to a buffer of length ::XLT_KEY_SIZE containing the dangle_key key set by xnd_xlt_setup().
|
|
\param[out] data points to a buffer of length ::XLT_BANK_SIZE that will receice the decrypted value.
|
|
\return returns ::XLT_ERROR_SUCCESS on success, an \ref xlt_Errors "error code" on failure.
|
|
|
|
\remark xnd_xlt_decrypt_locked_data() retrieves the data in clear form of the content of a memory bank collected with a previous xnd_xlt_read_locked() call.
|
|
xnd_xlt_decrypt_locked_data() and xnd_xlt_read_locked() are used in a server client memory bank read operation. The xnd_xlt_read_locked() doesn't need of any password
|
|
and cryptographic key to be used but produces an encrypted buffer that can be understood only by the holder of the <i>Dongle Key</i> crypto-key.
|
|
xnd_xlt_read_locked() can be executed by non trusted people to collect information. Afterwards xnd_xlt_decrypt_locked_data() allows the authorized parts to decrypt
|
|
and read the content of the memory bank.
|
|
|
|
The buffer returned by xnd_xlt_decrypt_locked_data() is ::XLT_KEY_SIZE bytes long, but only the first ::XLT_LOCKED_BANK_DATA_LENGTH bytes are the significant data
|
|
that can be written and used by the application. The remaining bytes are managed internally by the library and used for the 'locked bank' management.
|
|
These bytes convey information that may be retrieved using xnd_xlt_get_info_from_locked_bank(), such information are necessary for writing inside a locked bank.
|
|
\sa xnd_xlt_read_locked(), xnd_xlt_get_info_from_locked_bank()
|
|
|
|
*/
|
|
XND_LINK int XND_API xnd_xlt_decrypt_locked_data(XND_DEVICE_CONTEXT dev_ctx, const unsigned char* encrypted_data, const unsigned char* dongle_key, unsigned char* data);
|
|
|
|
/**
|
|
\ingroup xnd_xlt_bank
|
|
Retrieve the data in clear form of the content of a locked with <i>Lock2</i> memory bank.
|
|
|
|
See \ref xn_locked_memory.
|
|
\param[in] dev_ctx ::XND_DEVICE_CONTEXT handle referring to a real or fake device.
|
|
\param[in] encrypted_data points to a buffer of length ::XLT_LOCKED_TRANSFER_DATA.
|
|
\param[in] dongle_key points to a buffer of length ::XLT_KEY_SIZE containing the dangle_key key set by xnd_xlt_setup().
|
|
\param[out] data points to a buffer of length ::XLT_BANK_SIZE that will receice the decrypted value.
|
|
\return returns ::XLT_ERROR_SUCCESS on success, an \ref xlt_Errors "error code" on failure.
|
|
|
|
\remark xnd_xlt_decrypt_locked2_data() retrieves the data in clear form of the content of a memory bank collected with a previous xnd_xlt_read_locked() call.
|
|
xnd_xlt_decrypt_locked2_data() and xnd_xlt_read_locked() are used in a server client memory bank read operation. The xnd_xlt_read_locked() doesn't need of any password
|
|
and cryptographic key to be used but produces an encrypted buffer that can be understood only by the holder of the <i>Dongle Key</i> crypto-key.
|
|
xnd_xlt_read_locked() can be executed by non trusted people to collect information. Afterwards xnd_xlt_decrypt_locked2_data() allows the authorized parts to decrypt
|
|
and read the content of the memory bank.
|
|
|
|
The buffer returned by xnd_xlt_decrypt_locked2_data() is ::XLT_KEY_SIZE bytes long, but only the first ::XLT_LOCKED_BANK_DATA_LENGTH bytes are the significant data
|
|
that can be written and used by the application. The remaining bytes are managed internally by the library and used for the 'locked bank' management.
|
|
These bytes convey information that may be retrieved using xnd_xlt_get_info_from_locked_bank(), such information are necessary for writing inside a locked bank.
|
|
<p><b>Supported version</b>: this function is available on XLight devices version 1.01 or later.
|
|
\sa xnd_xlt_read_locked(), xnd_xlt_get_info_from_locked_bank()
|
|
*/
|
|
XND_LINK int XND_API xnd_xlt_decrypt_locked2_data(XND_DEVICE_CONTEXT dev_ctx, const unsigned char* encrypted_data, const unsigned char* dongle_key, unsigned char* data);
|
|
|
|
/**
|
|
\ingroup xnd_xlt_bank
|
|
Return information of a locked bank (both normal and advanced <i>Lock2</i> mode).
|
|
|
|
See \ref xn_locked_memory.
|
|
\param[in] dev_ctx ::XND_DEVICE_CONTEXT handle referring to a real or fake device.
|
|
\param[in] data points to a buffer of length ::XLT_BANK_SIZE, that contains the value retrieved from a locked bank by xnd_xlt_read() or xnd_xlt_decrypt_locked_data().
|
|
\param[out] pbank points to an unsigned int that will contain the bank number to which the data belongs. This parameter is optional and may be set to NULL.
|
|
\param[out] pcounter points to an unsigned int that will contain the current counter field of the locked bank. This parameter is optional and may be set to NULL.
|
|
\param[out] pserial points to an unsigned int that will contain the serial number of the locked bank. This parameter is optional and may be set to NULL.
|
|
\param[out] pgroup_number points to an unsigned int that will contain the group number of the locked bank. This parameter is optional and may be set to NULL.
|
|
\return returns ::XLT_ERROR_SUCCESS on success, an \ref xlt_Errors "error code" on failure.
|
|
\remark If the data passed to this function comes from a non locked bank the outcome of this function is meaningless.
|
|
\remark The 'data' argument may come from a xnd_xlt_decrypt_locked_data() or a local xnd_xlt_read() call.
|
|
*/
|
|
XND_LINK int XND_API xnd_xlt_get_info_from_locked_bank(XND_DEVICE_CONTEXT dev_ctx, const unsigned char* data, unsigned int* pbank, unsigned int* pcounter, unsigned int* pserial, unsigned int* pgroup_number);
|
|
|
|
/**
|
|
\ingroup xnd_xlt_device
|
|
Virginize (reset) a demo XLight device.
|
|
\remark It doesn't work at all on a virtual XLight device of an xNodus device.
|
|
\param[in] dev_ctx ::XND_DEVICE_CONTEXT handle referring to the selected device.
|
|
\return returns ::XLT_ERROR_SUCCESS on success, an \ref xlt_Errors "error code" on failure.
|
|
\remark This function may be useful for testing allowing to completely cleanup a DEMO device, that is it doesn't work onto standard devices.
|
|
A demo device is distinguished by standard ones by its serial number: it is set to the value '1'.
|
|
This function may be useful especially while testing xnd_xlt_bank_freeze() and xnd_xlt_bank_lock2() functions which on normal devices cannot be reverted.
|
|
|
|
\note OxySec supplies DEMO devices only for evaluation purpose and must be used only for testing on the standard devices.
|
|
*/
|
|
XND_LINK int XND_API xnd_xlt_virg_demo(XND_DEVICE_CONTEXT dev_ctx);
|
|
|
|
//\cond NOT_COMMENTED
|
|
XND_LINK int XND_API xnd_xlt_setserial(XND_DEVICE_CONTEXT dev_ctx, unsigned int sn);
|
|
//\endcond
|
|
|
|
/**
|
|
\ingroup xnd_xlt_sd
|
|
Get memory size information of the memory flash in <i>XLight SD</i> devices.
|
|
\remark This function is not supported by xNodus devices.
|
|
\param[in] dev_ctx ::XND_DEVICE_CONTEXT handle referring to the selected device.
|
|
\param[out] p_mem_size_in_blocks points to an unsigned integer receiving the size in memory blocks (512 bytes) of the overall memory flash.
|
|
\param[out] p_enc_mem_size_in_blocks points to an unsigned integer receiving the size in memory blocks of the encrypted disk. If not present the return value is zero.
|
|
\return returns ::XLT_ERROR_SUCCESS on success, an \ref xlt_Errors "error code" on failure.
|
|
\see \ref xn_SDMEM.
|
|
*/
|
|
XND_LINK int XND_API xnd_xlt_storage_get_mem_size(XND_DEVICE_CONTEXT dev_ctx, unsigned int *p_mem_size_in_blocks, unsigned int *p_enc_mem_size_in_blocks);
|
|
|
|
/**
|
|
\ingroup xnd_xlt_sd
|
|
Initialize the memory flash of an <i>XLight SD</i> device.
|
|
\remark This function is not supported by xNodus devices.
|
|
\param[in] dev_ctx ::XND_DEVICE_CONTEXT handle referring to the selected device.
|
|
\param[in] locked_mem_size_in_blocks the size in blocks of the desired size for the encrypted disk. If no encrypted disk is desired set this value to '0' (zero).
|
|
\param[in] dongle_key points to a buffer containing the <i>Dongle Key</i> set by xnd_xlt_setup() function.
|
|
\param[in] disk_password points to a buffer of length ::XLT_DISK_PASSWORD_SIZE containing the password that will be used to mount and unmount the encrypted disk.
|
|
\return returns ::XLT_ERROR_SUCCESS on success, an \ref xlt_Errors "error code" on failure.
|
|
\see \ref xn_SDMEM.
|
|
*/
|
|
XND_LINK int XND_API xnd_xlt_storage_set(XND_DEVICE_CONTEXT dev_ctx, unsigned int locked_mem_size_in_blocks, const unsigned char* dongle_key, const unsigned char* disk_password);
|
|
|
|
/**
|
|
\ingroup xnd_xlt_sd
|
|
Mount the encrypted disk of an <i>XLight SD</i> device.
|
|
\remark This function is not supported by xNodus devices.
|
|
\param[in] dev_ctx ::XND_DEVICE_CONTEXT handle referring to the selected device.
|
|
\param[in] disk_password points to a buffer of length ::XLT_DISK_PASSWORD_SIZE containing the password set by xnd_xlt_storage_set() function.
|
|
\return returns ::XLT_ERROR_SUCCESS on success, an \ref xlt_Errors "error code" on failure.
|
|
\see \ref xn_SDMEM.
|
|
*/
|
|
XND_LINK int XND_API xnd_xlt_storage_unlock(XND_DEVICE_CONTEXT dev_ctx, const unsigned char* disk_password);
|
|
|
|
/**
|
|
\ingroup xnd_xlt_sd
|
|
Mount the encrypted disk of an <i>XLight SD</i> device with read only access.
|
|
\remark This function is not supported by xNodus devices.
|
|
\param[in] dev_ctx ::XND_DEVICE_CONTEXT handle referring to the selected device.
|
|
\param[in] disk_password points to a buffer of length ::XLT_DISK_PASSWORD_SIZE containing the password set by xnd_xlt_storage_set() function.
|
|
\return returns ::XLT_ERROR_SUCCESS on success, an \ref xlt_Errors "error code" on failure.
|
|
\see \ref xn_SDMEM.
|
|
*/
|
|
XND_LINK int XND_API xnd_xlt_storage_unlock_ro(XND_DEVICE_CONTEXT dev_ctx, const unsigned char* disk_password);
|
|
|
|
/**
|
|
\ingroup xnd_xlt_sd
|
|
Unmount the encrypted disk of an <i>XLight SD</i> device.
|
|
\remark This function is not supported by xNodus devices.
|
|
\param[in] dev_ctx ::XND_DEVICE_CONTEXT handle referring to the selected device.
|
|
\param[in] disk_password points to a buffer of length ::XLT_DISK_PASSWORD_SIZE containing the password set by xnd_xlt_storage_set() function.
|
|
\return returns ::XLT_ERROR_SUCCESS on success, an \ref xlt_Errors "error code" on failure.
|
|
\see \ref xn_SDMEM.
|
|
*/
|
|
XND_LINK int XND_API xnd_xlt_storage_lock(XND_DEVICE_CONTEXT dev_ctx, const unsigned char* disk_password);
|
|
|
|
//\cond NOT_COMMENTED
|
|
XND_LINK int XND_API xnd_xlt_reserved(XND_DEVICE_CONTEXT dev_ctx, const unsigned char* direct_cmd, unsigned int direct_cmd_len, unsigned char* direct_resp, unsigned int direct_resp_size);
|
|
XND_LINK int XND_API xnd_xlt_reserved2(XND_DEVICE_CONTEXT dev_ctx, const unsigned char* dongle_key, unsigned int serial, const unsigned char* oxy_pre_cmd, unsigned int oxy_pre_cmd_len, unsigned char* direct_resp, unsigned int direct_resp_size);
|
|
XND_LINK int XND_API xnd_xlt_xlightsd_switch_to_nondemo(XND_DEVICE_CONTEXT dev_ctx);
|
|
XND_LINK int XND_API xnd_xlt_get_device_name(XND_DEVICE_CONTEXT dev_ctx, char* device_name, unsigned int device_name_size);
|
|
//\endcond
|
|
|
|
/**
|
|
\ingroup xnd_xlt_counter
|
|
Update and get the value of a counter.
|
|
See \ref xn_TIMER_COUNTERS for an introduction to timer and counters management.
|
|
\param[in] dev_ctx ::XND_DEVICE_CONTEXT handle referring to the selected device.
|
|
\param[in] counter index of the counter to be used. This entry may take values from 0 to ::XLT_COUNTERS_NUM - 1.
|
|
\param[in] sub_value value to be subtracted to the indexed counter. If this value is 0 (zero) the counter value is read without modifying it.
|
|
\param[out] p_new_value point to an unsigned int value that will receive the value of the counter after the subtraction.
|
|
\return returns ::XLT_ERROR_SUCCESS on success, an \ref xlt_Errors "error code" on failure.
|
|
|
|
If sub_value is greater than the current counter value, its new value will be zero and the function returns ::XLT_ERROR_SUCCESS. This is still the case also if the counter value is already zero.
|
|
|
|
\see \ref xn_TIMER_COUNTERS.
|
|
*/
|
|
XND_LINK int XND_API xnd_xlt_update_get_counter(XND_DEVICE_CONTEXT dev_ctx, unsigned int counter, unsigned int sub_value, unsigned int* p_new_value);
|
|
|
|
/**
|
|
\ingroup xnd_xlt_timer
|
|
Retrieve the current value of the timer.
|
|
See \ref xn_TIMER_COUNTERS for an introduction to timer and counters management.
|
|
\param[in] dev_ctx ::XND_DEVICE_CONTEXT handle referring to the selected device.
|
|
\param[out] p_value point to an unsigned int value that will receive the current value of the timer.
|
|
\return returns ::XLT_ERROR_SUCCESS on success, an \ref xlt_Errors "error code" on failure.
|
|
\see \ref xn_TIMER_COUNTERS.
|
|
*/
|
|
XND_LINK int XND_API xnd_xlt_get_timer(XND_DEVICE_CONTEXT dev_ctx, unsigned int* p_value);
|
|
|
|
/**
|
|
\ingroup xnd_xlt_counter
|
|
Generate a command buffer to set a counter.
|
|
See \ref xn_TIMER_COUNTERS for an introduction to timer and counters management.
|
|
\param[in] dev_ctx ::XND_DEVICE_CONTEXT handle referring to a real or fake device.
|
|
\param[in] counter_cmd points to the structure ::XLT_COUNTER_CMD containing the settings to be applied to a counter.
|
|
\param[in] dongle_key points to the value of the <i>Dongle Key</i> set up by xnd_xlt_setup() function.
|
|
\param[out] enc_cmd points to a buffer that will receive the encrypted form of the command.
|
|
\param[in] enc_cmd_size length of the buffer pointed by enc_cmd.
|
|
\param[out] p_enc_cmd_len points to an unsigned integer that will contain the number of bytes copied in enc_cmd. This entry may be set also to 0 (NULL).
|
|
\return returns ::XLT_ERROR_SUCCESS on success, an \ref xlt_Errors "error code" on failure.
|
|
\see \ref xn_TIMER_COUNTERS.
|
|
*/
|
|
XND_LINK int XND_API xnd_xlt_generate_counter_settings(XND_DEVICE_CONTEXT dev_ctx, const XLT_COUNTER_CMD* counter_cmd, const unsigned char* dongle_key, unsigned char* enc_cmd, unsigned int enc_cmd_size, unsigned int* p_enc_cmd_len);
|
|
|
|
/**
|
|
\ingroup xnd_xlt_tc
|
|
Apply a timer or counter command onto the device.
|
|
See \ref xn_TIMER_COUNTERS for an introduction to timer and counters management.
|
|
\param[in] dev_ctx ::XND_DEVICE_CONTEXT handle referring to the selected device.
|
|
\param[in] enc_cmd point to a buffer containing the encrypted command to be applied to the device.
|
|
\param[in] enc_cmd_len the length of the encrypted command.
|
|
\return returns ::XLT_ERROR_SUCCESS on success, an \ref xlt_Errors "error code" on failure.
|
|
\see \ref xn_TIMER_COUNTERS.
|
|
*/
|
|
XND_LINK int XND_API xnd_xlt_enc_apply_timer_counter(XND_DEVICE_CONTEXT dev_ctx, const unsigned char* enc_cmd, unsigned int enc_cmd_len);
|
|
|
|
/**
|
|
\ingroup xnd_xlt_counter
|
|
Read in encrypted form the current state of all the counters of the device.
|
|
See \ref xn_TIMER_COUNTERS for an introduction to timer and counters management.
|
|
\param[in] dev_ctx ::XND_DEVICE_CONTEXT handle referring to the selected device.
|
|
\param[out] enc_data points to a buffer that will receive the encrypted counters data retrieved from the XLight dongle.
|
|
\param[in] enc_data_size length of the buffer pointed by enc_data.
|
|
\param[out] p_enc_data_len points to an unsigned integer that will receive the number of bytes copied in enc_data. This entry may be set also to 0 (NULL).
|
|
\return returns ::XLT_ERROR_SUCCESS on success, an \ref xlt_Errors "error code" on failure.
|
|
\see \ref xn_TIMER_COUNTERS.
|
|
*/
|
|
XND_LINK int XND_API xnd_xlt_enc_read_counters(XND_DEVICE_CONTEXT dev_ctx, unsigned char* enc_data, unsigned int enc_data_size, unsigned int* p_enc_data_len);
|
|
|
|
/**
|
|
\ingroup xnd_xlt_timer
|
|
Generate a command buffer to a set the timer.
|
|
See \ref xn_TIMER_COUNTERS for an introduction to timer and counters management.
|
|
\param[in] dev_ctx ::XND_DEVICE_CONTEXT handle referring to a real or fake device.
|
|
\param[in] timer_cmd points to the structure ::XLT_TIMER_CMD containing the settings to be applied to the timer.
|
|
\param[in] dongle_key points to the value of the <i>Dongle Key</i> set up by xnd_xlt_setup() function.
|
|
\param[out] enc_cmd points to a buffer that will receive the encrypted form of the command.
|
|
\param[in] enc_cmd_size length of the buffer pointed by enc_cmd.
|
|
\param[out] p_enc_cmd_len points to an unsigned integer that will contain the number of bytes copied in enc_cmd. This entry may be set also to 0 (NULL).
|
|
\return returns ::XLT_ERROR_SUCCESS on success, an \ref xlt_Errors "error code" on failure.
|
|
\see \ref xn_TIMER_COUNTERS.
|
|
*/
|
|
XND_LINK int XND_API xnd_xlt_generate_timer_settings(XND_DEVICE_CONTEXT dev_ctx, const XLT_TIMER_CMD* timer_cmd, const unsigned char* dongle_key, unsigned char* enc_cmd, unsigned int enc_cmd_size, unsigned int* p_enc_cmd_len);
|
|
|
|
/**
|
|
\ingroup xnd_xlt_timer
|
|
Generate a command buffer to increase the timer value.
|
|
See \ref xn_TIMER_COUNTERS for an introduction to timer and counters management.
|
|
\param[in] dev_ctx ::XND_DEVICE_CONTEXT handle referring to a real or fake device.
|
|
\param[in] timer_add_cmd points to the structure ::XLT_TIMER_ADD_CMD containing the add timer settings to be applied.
|
|
\param[in] dongle_key points to the value of the <i>Dongle Key</i> set up by xnd_xlt_setup() function.
|
|
\param[out] enc_cmd points to a buffer that will receive the encrypted form of the command.
|
|
\param[in] enc_cmd_size length of the buffer pointed by enc_cmd.
|
|
\param[out] p_enc_cmd_len points to an unsigned integer that will contain the number of bytes copied in enc_cmd. This entry may be set also to 0 (NULL).
|
|
\return returns ::XLT_ERROR_SUCCESS on success, an \ref xlt_Errors "error code" on failure.
|
|
\see \ref xn_TIMER_COUNTERS.
|
|
*/
|
|
XND_LINK int XND_API xnd_xlt_generate_timer_add_settings(XND_DEVICE_CONTEXT dev_ctx, const XLT_TIMER_ADD_CMD* timer_add_cmd, const unsigned char* dongle_key, unsigned char* enc_cmd, unsigned int enc_cmd_size, unsigned int* p_enc_cmd_len);
|
|
|
|
/**
|
|
\ingroup xnd_xlt_timer
|
|
Read in encrypted form the current state the device timer.
|
|
See \ref xn_TIMER_COUNTERS for an introduction to timer and counters management.
|
|
\param[in] dev_ctx ::XND_DEVICE_CONTEXT handle referring to the selected device.
|
|
\param[out] enc_data points to a buffer that will receive the encrypted timer data retrieved from the XLight dongle.
|
|
\param[in] enc_data_size length of the buffer pointed by enc_data.
|
|
\param[out] p_enc_data_len points to an unsigned integer that will receive the number of bytes copied in enc_data. This entry may be set also to 0 (NULL).
|
|
\return returns ::XLT_ERROR_SUCCESS on success, an \ref xlt_Errors "error code" on failure.
|
|
\see \ref xn_TIMER_COUNTERS.
|
|
*/
|
|
XND_LINK int XND_API xnd_xlt_enc_read_timer(XND_DEVICE_CONTEXT dev_ctx, unsigned char* enc_data, unsigned int enc_data_size, unsigned int* p_enc_data_len);
|
|
|
|
/**
|
|
\ingroup xnd_xlt_tc
|
|
Decrypt encrypted data from the device regarding timer or counters.
|
|
This function also extract data from encrypted commands.
|
|
See \ref xn_TIMER_COUNTERS for an introduction to timer and counters management.
|
|
\param[in] dev_ctx ::XND_DEVICE_CONTEXT handle referring to a real or fake device.
|
|
\param[in] enc_data points to encrypted data retrieved from the device or containing an encrypted command.
|
|
\param[in] enc_data_len length of the encrypted buffer.
|
|
\param[in] dongle_key points to the value of the <i>Dongle Key</i> set up by xnd_xlt_setup() function.
|
|
\param[out] retrieved_data points to an instance of structure ::XLT_TIMER_COUNTER_INFO that will contain the decryption of the data or command passed to this function.
|
|
\return returns ::XLT_ERROR_SUCCESS on success, an \ref xlt_Errors "error code" on failure.
|
|
\see \ref xn_TIMER_COUNTERS.
|
|
*/
|
|
XND_LINK int XND_API xnd_xlt_timer_counters_retrieve(XND_DEVICE_CONTEXT dev_ctx, const unsigned char* enc_data, unsigned int enc_data_len, const unsigned char* dongle_key, XLT_TIMER_COUNTER_INFO* retrieved_data);
|
|
|
|
/**
|
|
\ingroup xnd_xlt_date
|
|
Read in encrypted form the current state of the date license management of the device.
|
|
See \ref xn_DATE_LICENSING for an introduction to XLight license management based on the date.
|
|
\param[in] dev_ctx ::XND_DEVICE_CONTEXT handle referring to the selected device.
|
|
\param[out] enc_data points to a buffer that will receive the encrypted date license data retrieved from the XLight dongle.
|
|
\param[in] enc_data_size length of the buffer pointed by enc_data.
|
|
\param[out] p_enc_data_len points to an unsigned integer that will receive the number of bytes copied in enc_data. This entry may be set also to 0 (NULL).
|
|
\return returns ::XLT_ERROR_SUCCESS on success, an \ref xlt_Errors "error code" on failure.
|
|
See \ref xn_DATE_LICENSING
|
|
*/
|
|
XND_LINK int XND_API xnd_xlt_enc_read_date(XND_DEVICE_CONTEXT dev_ctx, unsigned char* enc_data, unsigned int enc_data_size, unsigned int* p_enc_data_len);
|
|
|
|
/**
|
|
\ingroup xnd_xlt_date
|
|
Read the current state of the date license management of the device.
|
|
See \ref xn_DATE_LICENSING for an introduction to XLight license management based on the date.
|
|
\param[in] dev_ctx ::XND_DEVICE_CONTEXT handle referring to the selected device.
|
|
\param[out] date_info points to a XLT_DATE_DATA struct that will receive the date license data of the connected device.
|
|
\return returns ::XLT_ERROR_SUCCESS on success, an \ref xlt_Errors "error code" on failure.
|
|
\note xnd_xlt_read_date() can be run by the protected application to see the current status of the license but some ::XLT_DATE_DATA entries are set always to zero and can be collected only using
|
|
remote functions. Such entries are:
|
|
<ul>
|
|
<li>functions_to_lock_mask,
|
|
<li>device_time,
|
|
<li>cmd_counter,
|
|
<li>max_missing_update_date_error,
|
|
<li>max_missing_update_signed_date_error and
|
|
<li>max_update_date_error.
|
|
</ul>
|
|
See \ref xn_DATE_LICENSING
|
|
*/
|
|
XND_LINK int XND_API xnd_xlt_read_date(XND_DEVICE_CONTEXT dev_ctx, XLT_DATE_DATA* date_info);
|
|
|
|
/**
|
|
\ingroup xnd_xlt_date
|
|
Set the current time (date) of the device.
|
|
See \ref xn_DATE_LICENSING for an introduction to XLight license management based on the date.
|
|
\param[in] dev_ctx ::XND_DEVICE_CONTEXT handle referring to the selected device.
|
|
\param[in] time the current Unix Time.
|
|
\return returns ::XLT_ERROR_SUCCESS on success, an \ref xlt_Errors "error code" on failure.
|
|
See \ref xn_DATE_LICENSING
|
|
*/
|
|
XND_LINK int XND_API xnd_xlt_set_date(XND_DEVICE_CONTEXT dev_ctx, unsigned int time);
|
|
|
|
/**
|
|
\ingroup xnd_xlt_date
|
|
Retrieve the challenge buffer generated by the XLight device for update signed update (\ref xn_SIGNED_DATE_UPDATE_CONSTRAINT)
|
|
The challenge buffer need to be used for setting the signed date onto the device
|
|
See \ref xn_DATE_LICENSING for an introduction to XLight license management based on the date.
|
|
\param[in] dev_ctx ::XND_DEVICE_CONTEXT handle referring to the selected device.
|
|
\param[out] enc_challenge points to a buffer that will receive an encoded form of the challenge buffer generated by the device. The length of the buffer must be not less than ::XLT_DATE_ENC_CHALLENGE_SIZE bytes long.
|
|
\param[in] enc_challenge_size length of the buffer pointed by challenge.
|
|
\param[out] p_enc_challenge_len points to an unsigned integer that will receive the length of the bytes copied in challenge. This entry may be set also to 0 (NULL).
|
|
\return returns ::XLT_ERROR_SUCCESS on success, an \ref xlt_Errors "error code" on failure.
|
|
See \ref xn_DATE_LICENSING
|
|
*/
|
|
XND_LINK int XND_API xnd_xlt_date_get_challenge(XND_DEVICE_CONTEXT dev_ctx, unsigned char* enc_challenge, unsigned int enc_challenge_size, unsigned int* p_enc_challenge_len);
|
|
|
|
/**
|
|
\ingroup xnd_xlt_date
|
|
Generate the license date expiration command
|
|
See \ref xn_DATE_LICENSING for an introduction to XLight license management based on the date (and the \ref xn_SetDateExpiration for an example of xnd_xlt_generate_date_expiration_cmd() usage).
|
|
\param[in] dev_ctx ::XND_DEVICE_CONTEXT handle referring to a real or fake device.
|
|
\param[in] cmd points to the structure containing all the settings for the license expiration command.
|
|
\param[in] dongle_key points to the value of the <i>Dongle Key</i> set up by xnd_xlt_setup() function.
|
|
\param[out] enc_cmd points to a buffer that will receive the encrypted form of the command for setting the expiration license date of an XLight device. The length of the buffer must be not less than ::XLT_DATE_ENC_EXP_CMD_SIZE bytes long.
|
|
\param[in] enc_cmd_size length of the buffer pointed by enc_cmd.
|
|
\param[out] p_enc_cmd_len points to an unsigned integer that will receive the length of the bytes copied in enc_cmd. This entry may be set also to 0 (NULL).
|
|
\return returns ::XLT_ERROR_SUCCESS on success, an \ref xlt_Errors "error code" on failure.
|
|
See \ref xn_DATE_LICENSING
|
|
*/
|
|
XND_LINK int XND_API xnd_xlt_generate_date_expiration_cmd(XND_DEVICE_CONTEXT dev_ctx, const XLT_DATE_SET_EXPIRATION_CMD* cmd, const unsigned char* dongle_key, unsigned char* enc_cmd, unsigned int enc_cmd_size, unsigned int* p_enc_cmd_len);
|
|
|
|
/**
|
|
\ingroup xnd_xlt_date
|
|
Generate the signed date command.
|
|
This command uses the challenge retrieved by the XLight device using the function xnd_xlt_date_get_challenge() and decoded by xnd_xlt_date_enc_retrieve().
|
|
See \ref xn_DATE_LICENSING for an introduction to XLight license management based on the date.
|
|
\param[in] dev_ctx ::XND_DEVICE_CONTEXT handle referring to a real or fake device.
|
|
\param[in] time current Unix Time.
|
|
\param[in] challenge the challenge buffer generated by the dongle.
|
|
\param[in] challenge_len length of the challenge entry.
|
|
\param[in] dongle_key points to the value of the <i>Dongle Key</i> set up by xnd_xlt_setup() function.
|
|
\param[out] enc_cmd points to a buffer that will receive the encrypted form of the command for the signed update of the time of the device. The length of the buffer must be not less than ::XLT_DATE_SIG_UPD_CMD_SIZE bytes long.
|
|
\param[in] enc_cmd_size length of the buffer pointed by enc_cmd.
|
|
\param[out] p_enc_cmd_len points to an unsigned integer that will receive the length of the bytes copied in enc_cmd. This entry may be set also to 0 (NULL).
|
|
\return returns ::XLT_ERROR_SUCCESS on success, an \ref xlt_Errors "error code" on failure.
|
|
\note The challenge entry is not the enc_challenge argument returned by the function xnd_xlt_date_get_challenge(), but this is the challenge buffer of the structure ::XLT_DATE_CHALLENGE returned by xnd_xlt_date_enc_retrieve().
|
|
See \ref xn_DATE_LICENSING
|
|
*/
|
|
XND_LINK int XND_API xnd_xlt_generate_signed_date_cmd(XND_DEVICE_CONTEXT dev_ctx, unsigned int time, const unsigned char* challenge, unsigned int challenge_len, const unsigned char* dongle_key, unsigned char* enc_cmd, unsigned int enc_cmd_size, unsigned int* p_enc_cmd_len);
|
|
|
|
/**
|
|
\ingroup xnd_xlt_date
|
|
Apply both license expiration setting and signed date update to the XLight device.
|
|
See \ref xn_DATE_LICENSING for an introduction to XLight license management based on the date.
|
|
\param[in] dev_ctx ::XND_DEVICE_CONTEXT handle referring to the selected device.
|
|
\param[in] enc_cmd point to a buffer containing the encrypted command to be applied to the device.
|
|
\param[in] enc_cmd_len the length of the encrypted command.
|
|
\return returns ::XLT_ERROR_SUCCESS on success, an \ref xlt_Errors "error code" on failure.
|
|
See \ref xn_DATE_LICENSING
|
|
*/
|
|
XND_LINK int XND_API xnd_xlt_apply_date_enc_cmd(XND_DEVICE_CONTEXT dev_ctx, const unsigned char* enc_cmd, unsigned int enc_cmd_len);
|
|
|
|
/**
|
|
\ingroup xnd_xlt_date
|
|
Decrypt the encrypted data returned by the device regarding the date license settings.
|
|
This function also extract data from encrypted commands for date management.
|
|
See \ref xn_DATE_LICENSING for an introduction to XLight license management based on the date.
|
|
\param[in] dev_ctx ::XND_DEVICE_CONTEXT handle referring to a real or fake device.
|
|
\param[in] enc_data points to encrypted data retrieved from the device or containing an encrypted command.
|
|
\param[in] enc_data_len length of the encrypted buffer.
|
|
\param[in] dongle_key points to the value of the <i>Dongle Key</i> set up by xnd_xlt_setup() function.
|
|
\param[out] retrieved_data points to an instance of structure ::XLT_DATE_INFO that will contain the decryption of the data or command passed to this function.
|
|
\return returns ::XLT_ERROR_SUCCESS on success, an \ref xlt_Errors "error code" on failure.
|
|
See \ref xn_DATE_LICENSING
|
|
*/
|
|
XND_LINK int XND_API xnd_xlt_date_enc_retrieve(XND_DEVICE_CONTEXT dev_ctx, const unsigned char* enc_data, unsigned int enc_data_len, const unsigned char* dongle_key, XLT_DATE_INFO* retrieved_data);
|
|
|
|
/**
|
|
\ingroup xnd_xlt_date
|
|
Date management function.
|
|
This function can take care of all the date management for the XLight device.
|
|
See \ref xn_DATE_LICENSING for an introduction to XLight license management based on the date (and expecially the paragraph \ref xn_AUTO_MANAGE_DATE_UPDATE).
|
|
An XLight device with date based licensing needs to be regularly accessed for setting its signed time and "normal" (non signed) time.
|
|
The non automatic functions used for such tasks are the xnd_xlt_apply_date_enc_cmd() (in conjunction with other vendor side operation) for the signed time and the xnd_xlt_set_date() for the non signed time.
|
|
xlt_date_manage() is able to completely substitute these tasks and regularly update the device also accessing internet services for getting signed update time.
|
|
\param[in] dev_ctx ::XND_DEVICE_CONTEXT handle referring to a real or fake device.
|
|
\param[in] cmd one of the \ref xlt_date_manage_cmd.
|
|
\param[in] device device index for the selection of a specific XLight device. This value runs from 0 to ::XLT_DEVICE_EXT_MAX -1.
|
|
\param[in] options the options of the command specified by the cmd argument.
|
|
\param[in] args points to a string containing arguments for addressing internet URL for signed time update or NTP time service.
|
|
\param[in] label points to a buffer with length of ::XLT_LABEL_SIZE byte containing the label of the XLight device to be addressed. If this entry is set to NULL, every device is addressed.
|
|
\return returns ::XLT_ERROR_SUCCESS on success, an \ref xlt_Errors "error code" on failure.
|
|
|
|
\note The device argument is considered only when the cmd argument has values \ref ::XLT_DATE_MANAGE_DO_SET_TIME and ::XLT_DATE_MANAGE_DO_SET_TIME_ASYNC.
|
|
|
|
The entry <i>options</i> and <i>args</i> gets values with different meaning depending on the value of the cmd entry:
|
|
|
|
when <i>cmd</i> is chosen among
|
|
<ul>
|
|
<li>::XLT_DATE_MANAGE_AUTO_START
|
|
<li>::XLT_DATE_MANAGE_DO_SET_TIME
|
|
<li>::XLT_DATE_MANAGE_DO_SET_TIME_ASYNC
|
|
</ul>
|
|
|
|
The <i>options</i> entry takes the values shown here: \ref DATE_OPT_VAL; while <i>args</i> is a string containing web addresses to reach an NTP service or the OxySec signed date service:
|
|
see \ref xn_AUTO_MANAGE_DATE_UPDATE to see how to build it up.
|
|
|
|
When <i>cmd</i> is ::XLT_DATE_MANAGE_SET_IDLE_TIME_SEC the <i>options</i> entry represents the second of tha new idle value (that is the time elapsing from one update test cicle and the other). Usually you don't need to
|
|
use this command value. The <i>args</i> entry is ignored.
|
|
|
|
When <i>cmd</i> is ::XLT_DATE_MANAGE_MAKE_LOGS the <i>options</i> entry is considered as a boolean value: '1' starts the log management, '0' stops it (the default is no log, so you need to activate it to get the log). The <i>args</i> entry is ignored.
|
|
|
|
When <i>cmd</i> is ::XLT_DATE_MANAGE_LOG_ONLY_ERROR the <i>options</i> entry is considered as a boolean value: '1' makes the log manager to keep track only of errors, '0' makes the log manager to keep track of every event (the defalut is '0'). The <i>args</i> entry is ignored.
|
|
|
|
When <i>cmd</i> is ::XLT_DATE_MANAGE_LOG_SET_QUEUE_LEN the <i>options</i> entry is the value of the desired log buffer, that is the maximum number of the log records that can be taken. When that number is passed the older records are discarded.
|
|
The default value for this entry is 10000. The <i>args</i> entry is ignored.
|
|
|
|
For every other value of the <i>cmd</i> entry <i>options</i> and <i>args</i> are ignored.
|
|
See \ref xn_DATE_LICENSING
|
|
*/
|
|
XND_LINK int XND_API xnd_xlt_date_manage(XND_DEVICE_CONTEXT dev_ctx, unsigned int cmd, unsigned int device, unsigned int options, const char* args, const unsigned char* label);
|
|
|
|
/**
|
|
\ingroup xnd_xlt_date
|
|
Retrieve the number of log records collected by the automatic date management process issued by xnd_xlt_date_manage().
|
|
See \ref xn_DATE_LICENSING for an introduction to XLight license management based on the date.
|
|
\param[in] dev_ctx ::XND_DEVICE_CONTEXT handle referring to a real or fake device.
|
|
\param[out] p_num_entries points to an unsigned integer that will receive the number of log record currently collected.
|
|
\return returns ::XLT_ERROR_SUCCESS on success, an \ref xlt_Errors "error code" on failure.
|
|
See \ref xn_DATE_LICENSING
|
|
*/
|
|
XND_LINK int XND_API xnd_xlt_date_manage_get_num_log_records(XND_DEVICE_CONTEXT dev_ctx, unsigned int* p_num_entries);
|
|
|
|
/**
|
|
\ingroup xnd_xlt_date
|
|
Retrieve log records collected by the automatic date management process issued by xnd_xlt_date_manage().
|
|
See \ref xn_DATE_LICENSING for an introduction to XLight license management based on the date.
|
|
\param[in] dev_ctx ::XND_DEVICE_CONTEXT handle referring to a real or fake device.
|
|
\param[in] starting_index the index of the first record to read from the log.
|
|
\param[in] num_entries the number of entries to read from the log.
|
|
\param[out] date_log the array of XLT_DATE_LOG structure that will receive the log records. The array must contain not less then num_entries items.
|
|
\param[out] p_num_entries_retrieved points to an unsigned integer that will receive the number of entries copied into the date_log array. This entry may be set also to 0 (NULL).
|
|
\return returns ::XLT_ERROR_SUCCESS on success, an \ref xlt_Errors "error code" on failure.
|
|
See \ref xn_DATE_LICENSING
|
|
*/
|
|
XND_LINK int XND_API xnd_xlt_date_manage_get_log_records(XND_DEVICE_CONTEXT dev_ctx, unsigned int starting_index, unsigned int num_entries, XLT_DATE_LOG date_log[], unsigned int* p_num_entries_retrieved);
|
|
|
|
/**
|
|
\ingroup xnd_xlt_ss
|
|
Open a session on the device (see \ref xnd_session_on_xlight).
|
|
\remark This function is not supported by xNodus devices, use xnd_xlt_session_open() instead.
|
|
\param[in] dev_ctx ::XND_DEVICE_CONTEXT handle referring to the selected device.
|
|
\param[in] password points to a buffer of length ::XLT_PASSWORD_SIZE. It contains the password to be assigned to the device.
|
|
\param[out] p_already_open points to an unsigned integer that will contain '1' if the session was already open, and '0' if not. If the pointer p_already_open is set to zero the argument is ignored.
|
|
\return returns ::XLT_ERROR_SUCCESS on success, an \ref xlt_Errors "error code" on failure.
|
|
\remark If the device referenced is xNodus the argument p_already_open is always ignored.
|
|
*/
|
|
XND_LINK int XND_API xnd_xlt_c_open_session(XND_DEVICE_CONTEXT dev_ctx, const unsigned char* password, unsigned int* p_already_open);
|
|
|
|
/**
|
|
\ingroup xnd_xlt_ss
|
|
Close a session on the device (see \ref xnd_session_on_xlight).
|
|
\remark This function is not supported by xNodus devices, use xnd_xlt_session_close() instead.
|
|
\param[in] dev_ctx ::XND_DEVICE_CONTEXT handle referring to the selected device.
|
|
\return returns ::XLT_ERROR_SUCCESS on success, an \ref xlt_Errors "error code" on failure.
|
|
*/
|
|
XND_LINK int XND_API xnd_xlt_c_close_session(XND_DEVICE_CONTEXT dev_ctx);
|
|
//xnd_xlt_functions
|
|
|
|
|
|
//#define XND_XLT_MODULE_CONFIG_CMD_LEN 32
|
|
|
|
/**
|
|
\ingroup xnd_xlt_module
|
|
XLight command for setting the module mask inside an XLight device (see \ref xnd_modules).
|
|
\param[in] dev_ctx a generic device context handle.
|
|
\param[in] modules_mask a 64 bit variable that defines the modules that the protected application can open.
|
|
\param[in] dongle_key points to the dongle_key of the XLight device (see xnd_xlt_setup()).
|
|
\param[in] unix_time current time expressed in unix time.
|
|
\param[in] sn serial number of the target XLight device. If this entry is set to '0' every device will accept the command.
|
|
\param[out] enc_cmd points to a buffer that will receive the command for setting the module mask inside the specified XLight device using xnd_xlt_config_modules_apply().
|
|
\param[in] enc_cmd_size the size in bytes of the buffer pointed by enc_cmd.
|
|
\param[out] p_enc_cmd_len points to an unsigned integer that will receive the actual length of the retrieved command written in enc_cmd.
|
|
\return returns ::XLT_ERROR_SUCCESS on success, an \ref xlt_Errors "error code" on failure.
|
|
|
|
\remark The module support for XLight is based on a mask, because a module can be set (1) or inactive (0), there is no counting process to establish the number of instances of the pretected application that can gain access of the module,
|
|
here it is only possible to set 'all' or 'none'. The value 0x0000000000000001 set as usable the module 0, 0x0000000000000002 set as usable the module 1, ... 0x8000000000000000 set as usable the module 63. So to make active the modules
|
|
1,4, and 62 it must be used 0x4000000000000012.
|
|
|
|
\remark This command works only on XLight version 2.50 and later
|
|
\see xnd_xlt_config_modules_apply()
|
|
*/
|
|
XND_LINK int XND_API xnd_xlt_config_modules_cmd_wrap(XND_DEVICE_CONTEXT dev_ctx, XLT_ULONG_LONG modules_mask, const unsigned char* dongle_key, unsigned int unix_time, OPT unsigned int sn, unsigned char* enc_cmd, unsigned int enc_cmd_size, unsigned int* p_enc_cmd_len);
|
|
|
|
/**
|
|
\ingroup xnd_xlt_module
|
|
Write the managed module mask on an XLight device applying the command generated by the function xnd_xlt_config_modules_cmd_wrap() (see \ref xnd_modules).
|
|
\param[in] dev_ctx a device context referring to the desired XLight device.
|
|
\param[in] enc_cmd points to a buffer containing the encrypted command generated by xnd_xlt_config_modules_cmd_wrap()
|
|
\param[in] enc_cmd_len the length in bytes of the encrypted command.
|
|
\return returns ::XLT_ERROR_SUCCESS on success, an \ref xlt_Errors "error code" on failure.
|
|
\remark This command works only on XLight version 2.50 and later.
|
|
\see xnd_xlt_config_modules_cmd_wrap()
|
|
*/
|
|
XND_LINK int XND_API xnd_xlt_config_modules_apply(XND_DEVICE_CONTEXT dev_ctx, unsigned char* enc_cmd, unsigned int enc_cmd_len);
|
|
|
|
//#define XLT_MODULE_SET_KEY_CMD_LEN 272
|
|
/**
|
|
\ingroup xnd_xlt_module
|
|
XLight command for setting module challenge keys inside an XLight device (see \ref xnd_module_challenge).
|
|
\param[in] dev_ctx a generic device context handle.
|
|
\param[in] key_type key type of used key. This value takes values from \ref xnd_info_key_type.
|
|
\param[in] key points to a buffer containing a key expressed in XLight or xNodus format (see \ref xnd_key_data).
|
|
\param[in] key_len the length of the key entry.
|
|
\param[in] dongle_key points to the dongle_key of the XLight device (see xnd_xlt_setup()).
|
|
\param[in] sn serial number of the target XLight device. If this entry is set to '0' every device will accept the command.
|
|
\param[out] enc_cmd points to a buffer that will receive the command for setting the specific key inside the specified XLight device using xnd_xlt_set_modules_key_apply().
|
|
\param[in] enc_cmd_size the size in bytes of the buffer pointed by enc_cmd.
|
|
\param[out] p_enc_cmd_len points to an unsigned integer that will receive the actual length of the retrieved command written in enc_cmd.
|
|
\return returns ::XLT_ERROR_SUCCESS on success, an \ref xlt_Errors "error code" on failure.
|
|
\parblock
|
|
\remark Only one key type (among RSA 512, RSA 1024 and AES) for the module challenge can be present on the XLight device at a time (while xNodus can select any of the present non volatile keys).
|
|
\endparblock
|
|
\parblock
|
|
\remark This command works only on XLight version 2.50 and later
|
|
\endparblock
|
|
*/
|
|
XND_LINK int XND_API xnd_xlt_set_modules_key_cmd_wrap(XND_DEVICE_CONTEXT dev_ctx, unsigned int key_type, const unsigned char* key, unsigned int key_len, const unsigned char* dongle_key, OPT unsigned int sn, unsigned char* enc_cmd, unsigned int enc_cmd_size, unsigned int* p_enc_cmd_len);
|
|
|
|
/**
|
|
\ingroup xnd_xlt_module
|
|
Write a module challenge key on an XLight device applying the command generated by the function xnd_xlt_set_modules_key_cmd_wrap() (see \ref xnd_module_challenge).
|
|
\param[in] dev_ctx a device context referring to the desired XLight device.
|
|
\param[in] enc_cmd points to a buffer containing the encrypted command generated by xnd_xlt_set_modules_key_cmd_wrap()
|
|
\param[in] enc_cmd_len the length in bytes of the encrypted command.
|
|
\return returns ::XLT_ERROR_SUCCESS on success, an \ref xlt_Errors "error code" on failure.
|
|
|
|
\remark This command works only on XLight version 2.50 and later
|
|
*/
|
|
XND_LINK int XND_API xnd_xlt_set_modules_key_apply(XND_DEVICE_CONTEXT dev_ctx, const unsigned char* enc_cmd, unsigned int enc_cmd_len);
|
|
|
|
|
|
|
|
#ifdef __cplusplus
|
|
}
|
|
#endif
|
|
|
|
#endif //XND_H_1239854890
|