UniKey API Reference for C Language

From SecuTech Wiki
Revision as of 14:25, 10 April 2012 by Cloud (talk | contribs)
Jump to navigationJump to search


Find a UniKey dongle

API Prototype
long UniKey_Find( WORD* pHandle ,
DWORD* pSetting1 ,
DWORD* pSetting2 ) ;

Description
Check if a specific UniKey is attached to the USB port. This is the first API to start a UniKey session.

Parameters
Parameter Meaning
*pHandle [out] Dongle handle
*pSetting1 *[in] Working Mode (UniKey PRO only), useless for UniKey STD
[out] Hardware ID
*pSetting2 *[in] Access Mode (UniKey PRO only), useless for UniKey STD(UniKey PRO only)
[out] Number of dongle attached , useless for UniKey STD

Return values
Marco Value Meaning
SUCCESS 0 Success
ERROR_UNIKEY_NO_UNIEKY 200 No UniKey dongle


Find the Next UniKey dongle

API Prototype
Long UniKey_Find_Next( WORD* pHandle ,
DWORD* pSetting1 ,
DWORD* pSetting2 ) ;

Description
Check if another UniKey is attached to the USB port.

Parameters
Parameter Meaning
*pHandle [out] Dongle handle
*pSetting1 *[in] Working Mode (UniKey PRO only), useless for UniKey STD
[out] Hardware ID
*pSetting2 *[in] Access Mode (UniKey PRO only), useless for UniKey STD(UniKeyPro only)
[out] Number of dongle attached , useless for UniKey STD

Return values
Marco Value Meaning
SUCCESS 0 Success
ERROR_UNIKEY_NOMORE 214 No more dongle
ERROR_UNIKEY_NEED_FIND 215 No Find before Find_Next


Logon UniKey Dongle

API Prototype
long UniKey_User_Logon( WORD* pHandle ,
WORD* pPassword1 ,
WORD* pPassword2 ) ;
-------------------------------------------------------------------------------------------

For UniKey Drive, the API Prototype is UniKey_User_Logon (WORD* pHandle, DWORD* pPassword1, DWORD* pPassword2);
-------------------------------------------------------------------------------------------
Description
Logon a UniKey dongle with specified passwords. This API should be called in the released software in order to improve security.

Parameters
Parameter Meaning
*pPassword1 [in]Password 1
*pPassword2 [in]Password 2
*pHandle [out] Dongle handle

Return values
Marco Value Meaning
SUCCESS 0 Success
ERROR_UNIKEY_NOT_FOUND 200 No UniKey dongle
ERROR_UNIKEY_INVALID_PASSWORD 201 UniKey dongle found, but Basic passwords are incorrect
ERROR_UNIKEY_INVALID_PASSWORD_OR_ID 202 Wrong password or UniKey HID


Logon UniKey Dongle in vendor mode


API Prototype
long UniKey_Vender_Logon( WORD* pHandle ,
WORD* pPassword1 ,
WORD* pPassword2 ,
WORD* pPassword3 ,
WORD* pPassword4 ) ;
---------------------------------------------------------------------------------------------------
For UniKey Drive, the API Prototype is UniKey_Vender_Logon(WORD* pHandle, DWORD* pPassword1, DWORD* pPassword2, DWORD* pPassword3, DWORD* pPassword4);
---------------------------------------------------------------------------------------------------

Description
Logon a UniKey dongle in vendor mode with specified passwords. This API helps software vendors to logon the UniKey dongle in vendor mode, and get the full permission to UniKey dongle.
---------------------------------------------------------------------------------------------------
We do NOT advise you to enclose this API in the final released software. This API is only for software vendor’s usage.
--------------------------------------------------------------------------------------------------
If password3 or password4 is wrong while password1 and password2 is correct, the dongle is also logged on in user mode automatically.
---------------------------------------------------------------------------------------------------

Parameters
Parameter Meaning
*pPassword1 [in]Password 1
*pPassword2 [in]Password 2
*pPassword3 [in]Password 3
*pPassword4 [in]Password 4
*pHandle [out] Dongle handle

Return values
Marco Value Meaning
SUCCESS 0 Success
ERROR_UNIKEY_NOT_FOUND 200 No UniKey dongle
ERROR_UNIKEY_INVALID_PASSWORD 201 Found UniKey dongle, but Basic passwords are incorrect
ERROR_UNIKEY_INVALID_PASSWORD_OR_ID 202 Wrong password or UniKey HID


Logoff the UniKey dongle


API Prototype
long UniKey_Logoff( WORD* pHandle ) ;

Description
Logoff a UniKey dongle with a specific handle. This API should be called at the end of UniKey session.

Parameters
Parameter Meaning
*pHandle [in] Dongle handle

Return values
Marco Value Meaning
SUCCESS 0 Success
ERROR_UNIKEY_NOT_FOUND 200 No UniKey dongle
ERROR_UNIKEY_NEED_OPEN 212 No logon dongle before operating dongle


Get the UniKey dongle 's Type


API Prototype
long UniKey_Get_Type( WORD* pHandle ,
DWORD* type ) ;

Description
UniKey_Get_Type can help you get the type of the UniKey dongle.
The return value of type will indicate the type of the UniKey dongle.
UNIKEY_TYPE_TIME 101
UNIKEY_TYPE_PRO 102
UNIKEY_TYPE_STD 103

Parameters
Parameter Meaning
*pHandle [in] Dongle handle
*type [out] The value indicating the type of your UniKey dongle

Return values
Marco Value Meaning
SUCCESS 0 Success
ERROR_GET_TYPE 237 UniKey Get Type Error


Read UniKey dongle memory


API Prototype
long UniKey_Read_Memory( WORD* pHandle ,
WORD* pStartAddress ,
WORD* pBufferLength ,
BYTE* pBuffer ) ;


Description
Read the contents of the Memory. This API needs to be called after logon of a UniKey dongle.

Parameters
Parameter Meaning
*handle*pHandle [in] Dongle handle
*pStartAddress [in] Offset of Memory
*pBufferLenght [in] Number of bytes to read
pBbuffer [out] Pointer to the buffer containing the data to be read

Return values
Marco Value Meaning
SUCCESS 0 Success
ERROR_UNIKEY_INVALID_ADDR_OR_SIZE 204 Read/Write address or length is wrong
ERROR_UNIKEY_READ_MEMORY 207 Read Error
ERROR_UNIKEY_NEED_OPEN 212 No logon dongle before operating dongle
ERROR_UNIKEY_NEED_OPEN 215 No logon dongle before operating dongle


Write to UniKey dongle memory


API Prototype
long UniKey_Write_Memory( WORD* pHandle ,
WORD* pStartAddress ,
WORD* pBufferLength ,
BYTE* pBuffer ) ;

Description
Write data into the memory. This API needs to be called after logging on to a UniKey dongle.

Parameters
Parameter Meaning
*handle*pHandle [in] Dongle handle
*pStartAddress [in] Offset of the memory
*pBufferLength [in] Number of bytes to write
pBbuffer [in] Pointer to the buffer containing the data to be written

Return values
Marco Value Meaning
SUCCESS 0 Success
ERROR_UNIKEY_INVALID_ADDR_OR_SIZE 204 Read/Write address or length is wrong
ERROR_UNIKEY_WRITE_MEMORY 207 Write Error
ERROR_UNIKEY_NEED_OPEN 212 No logon dongle before operating dongle
ERROR_UNIKEY_VERIFY_ADV_PASSWORD 223 Advanced passwords (password3 and passowrd4) not verified


To write the last 2k memory (for 2048 – 4096), you need to verify all the 4 passwords （vendor mode） to obtain full permission to the dongle.
--------------------------------------------------------------------------------------------------

UniKey_Read_Memory and UniKey_Write_Memory provide basic reading and writing functions to the dongle. You can store general information via such functions. And various levels of security can be applied too.
--------------------------------------------------------------------------------------------------


Generate a Random Number


API Prototype
long UniKey_Random( WORD* pHandle ,
WORD* pReturn1 ,
WORD* pReturn2 ,
WORD* pReturn3 ,
WORD* pReturn4 ) ;

Description
Generate a random number from the dongle.

Parameters
Parameter Meaning
*pHandle [in] Dongle handle
*pReturn1 [out] Random number
*pReturn2 [out] Random number
*pReturn3 [out] Random number
*pReturn4 [out] Random number

Return values
Marco Value Meaning
SUCCESS 0 Success
ERROR_UNIKEY_NEED_OPEN 212 No logon dongle before operating dongle
ERROR_UNIKEY_RANDOM 209 Random number Error


UNIKEY_RANDOM is to generate a random number inside the dongle. The UniKey dongle computing engine generates the number and the hardware of the dongle is the seed for the random number.
--------------------------------------------------------------------------------------------------


Generate Seed Code Return Values


API Prototype
long UniKey_Seed( WORD* pHandle ,
DWORD* pSeed ,
WORD* pReturn1 ,
WORD* pReturn2 ,
WORD* pReturn3 ,
WORD* pReturn4 ) ;

Description
Get return codes from the input of a seed code. This API return for values which are related to pSeed and UniKey dongle’s password.

Parameters
Parameter Meaning
*pHandle [in] Dongle handle
*pSeed [in] Seed Code
*pReturn1 [out] Return Code 1
*pReturn2 [out] Return Code 2
*pReturn3 [out] Return Code 3
*pReturn4 [out] Return Code 4

Return values
Marco Value Meaning
SUCCESS 0 Success
ERROR_UNIKEY_NEED_OPEN 212 No logon dongle before operating dongle
ERROR_UNIKEY_SEED 210 Seed code Error


UniKey_Seed generate a set of seed codes. All of these seed codes are based on the password. It provides another method to verify the password and check the insertion of the dongle. Apart from this, the seed codes can be used to involve in other computation, for example, you use the seed returned as a 64-bit long encryption key.
---------------------------------------------------------------------------------------------------


Write the Soft ID


API Prototype
long UniKey_Write_SoftID( WORD* pHandle ,
DWORD* pSoftID ) ;

Description
Write the vendor defined SoftID.

Parameters
Parameter Meaning
*pHandle [in] Dongle handle
*pSoftID [in] Soft ID

Return values
Marco Value Meaning
SUCCESS 0 Success
ERROR_UNIKEY_NEED_OPEN 212 No logon dongle before operating dongle
ERROR_UNIKEY_SET_SOFTID 203 Set UniKey ID wrong
---------------------------------------------------------------------------------------------------

You need to verify all 4 passwords (vendor mode) to write the SoftID.
---------------------------------------------------------------------------------------------------

Read Soft ID
API Prototype
long UniKey_Read_SoftID( WORD* pHandle ,
DWORD* pSoftID ) ;

Description
Read the user defined SoftID.

Parameters
Parameter Meaning
*pHandle [in] Dongle handle
*pSoftID [out] Soft ID

Return values
Marco Value Meaning
SUCCESS 0 Success
ERROR_UNIKEY_NEED_OPEN 212 No logon dongle before operating dongle


UniKey_Write_SoftID and UniKey_Read_SoftID provide a means to make a soft (write-able) ID for each software. You can write different software ID for each software and call UNIKEY_READ_SOFTID to check if the software ID is correct.
---------------------------------------------------------------------------------------------------

Set a UniKey License module


API Prototype
long UniKey_Set_Module( WORD* pHandle ,
WORD* pModule ,
WORD* pValue ,
WORD* pDecrease ) ;

Description
To write a value to a specific UniKey license module and set the Decrement attribute.

Parameters
Parameter Meaning
*pHandle [in] Dongle handle
*pModule [in] License module Number
*pValue [in] License module Unit Value
*pDecrease [in] Decreasing attribute. If decreasing is allowed (1 = allowed, 0 = not allowed)

Return values
Marco Value Meaning
SUCCESS 0 Success
ERROR_UNIKEY_INVALID_ADDR_OR_SIZE 202 Read/Write address or length is wrong
ERROR_UNIKEY_NEED_OPEN 212 No logon dongle before operating dongle
ERROR_UNIKEY_MODULE 216 License module error


A successful operation will result in license module unit # “*pModule” storing value “*pValue” and the Decrement attribute set to “0” or “1”
---------------------------------------------------------------------------------------------------

You need verify 4 passwords (vendor mode) to set a module value successfully.
---------------------------------------------------------------------------------------------------

 

Get a UniKey License module


API Prototype
long UniKey_Get_Module( WORD* pHandle ,
WORD* pModule ,
WORD* pValue ) ;

Description
Get a value from a specific UniKey license module.

Parameters
Parameter Meaning
*pHandle [in] Dongle handle
*pModule [in] Module Number
*pValue [out] Return the value in module

Return values
Marco Value Meaning
SUCCESS 0 Success
ERROR_UNIKEY_INVALID_ADDR_OR_SIZE 202 Read/Write address or length is wrong
ERROR_UNIKEY_NEED_OPEN 212 No logon dongle before operating dongle
ERROR_UNIKEY_MODULE 216 License module error

You need verify 2 passwords (user mode) to get a module value successfully.
---------------------------------------------------------------------------------------------------

 

Check a UniKey License module


API Prototype
long UniKey_Check_Module( WORD* pHandle ,
WORD* pModule ,
WORD* pValue ,
WORD* pDecrease ) ;

Description
Read the attributes of a specific UniKey license module.

Parameters
Parameter Meaning
*pHandle [in] Dongle handle
*pModule [in] License module Number
*pValue [out] Validity (1 = license module value is not zero)
*pDecrease [out] Decrement attribute (1 = license module can be decreased)

Return values
Marco Value Meaning
SUCCESS 0 Success
ERROR_UNIKEY_INVALID_ADDR_OR_SIZE 202 Read/Write address or length is wrong
ERROR_UNIKEY_NEED_OPEN 212 No logon dongle before operating dongle
ERROR_UNIKEY_MODULE 216 License module error
---------------------------------------------------------------------------------------------------
A successful operation will result in “*pValue” with value from the Validity (1 = license module value is not zero), and “*pDecrease” with the value from the Decrement attribute (1 = license module can be decreased).

The value of a license module cannot be read out directly and it is invisible to end users.
---------------------------------------------------------------------------------------------------
---------------------------------------------------------------------------------------------------
UniKey_Set_Module and UniKey_Check_Module provide an easy mean to implement software limitation. For example, if you want to set a software can be only executed 3 times, so you can call UNIKEY_SET_MODULE to set a license module (let us say license module 0) as 3. And when each execution, we decrease the license module, if the license module is invalid (zero), we stop the software. Apart from this, we can implement a module-selling model with help of license module functions. For example, the software has four function modules, A, B, C and D. And we can map the function modules to the license module in the UniKey dongle. Let us say the function module A is mapped to license module 0, B to 1, C to 2 and D to 3. If a customer only buys function A, B, you just need to enable the license module 0 and 1, and leave 2 and 3 as zero. So only function module A and B can be executed. If the customer buys more function, you can use UniKey remote update function to update the dongle remotely.
--------------------------------------------------------------------------------------------------


Write Arithmetic


API Prototype
long UniKey_Write_Arithmetic( WORD* pHandle ,
WORD* pStartAddress ,
BYTE* pBuffer ) ;

Description
Write user-defined mathematical algorithms.

Parameters
Parameter Meaning
*pHandle [in] Dongle handle
*pStartAddress [in] Offset of first instruction
*pBuffer [in] Pointer to the algorithm command string

Return values
Marco Value Meaning
SUCCESS 0 Success
ERROR_UNIKEY_INVALID_ADDR_OR_SIZE 204 Read/Write address or length is wrong
ERROR_UNIKEY_NEED_OPEN 212 No logon dongle before operating dongle
ERROR_UNIKEY_AR_BAD_COMMAND 217 Arithmetic instruction Error
ERROR_UNIKEY_AR_UNKNOWN_OPCODE 218 Arithmetic operator Error
ERROR_UNIKEY_AR_WRON_GBEGIN 219 Const number can't use on first arithmetic instruction
ERROR_UNIKEY_AR_WRONG_END 220 Const number can't use on last arithmetic instruction
ERROR_UNIKEY_AR_VALUE_OVERFLOW 221 Const number > 63


---------------------------------------------------------------------------------------------------
A successful operation will result in the user-defined algorithm populated with the algorithm command string from the buffer.
--------------------------------------------------------------------------------------------------


UniKey_Write_Arithmetic is called when you write a series of algorithms into the dongle. This function is only called at software vendor side. For example, if you have a serial number generate algorithm, and you want to perform this algorithm inside the dongle, you need to call UniKey_Write_Arithmetic.
--------------------------------------------------------------------------------------------------


User-defined Algorithm Calculate 1


API Prototype
long UniKey_Calculate1( WORD* pHandle ,
DWORD* pStartAddress ,
DWORD* pModule ,
WORD* pRegA ,
WORD* pRegB ,
WORD* pRegC ,
WORD* pRegD ) ;

Description
Return the results of a calculation performed in UniKey, using input provided by the developer and the CALCULATE1 function.

Parameters
Parameter Meaning
*pHandle [in] Dongle handle
*pStartAddress [in] Start point of calculation
*pModule [in] License module number
*p1 [in, out] Register A
*p2 [in, out] Register B
*p3 [in, out] Register C
*p4 [in, out] Register D

Return value
Marco Value Meaning
SUCCESS 0 Success
ERROR_UNIKEY_INVALID_ADDR_OR_SIZE 204 Read/Write address or length is wrong
ERROR_UNIKEY_NEED_OPEN 212 No logon dongle before operating dongle
ERROR_UNIKEY_AR_BAD_COMMAND 217 Arithmetic instruction Error
ERROR_UNIKEY_AR_UNKNOWN_OPCODE 218 Arithmetic operator Error
ERROR_UNIKEY_AR_WRON_GBEGIN 219 Const number can't use on first arithmetic instruction
ERROR_UNIKEY_AR_WRONG_END 220 Const number can't use on last arithmetic instruction
ERROR_UNIKEY_AR_VALUE_OVERFLOW 221 Const number > 63


When the calculation starts, the values of other internal registers are listed in the table below.
E and F are reversed hardware ID byte wisely. For example, if the hardware is 0x12345678 (in Hex), and E will be 0x7856, and F will be 0x3412.
---------------------------------------------------------------------------------------------------
Internal Register Meaning
E HiWord of reversed hardware ID
F LoWord of reversed hardware ID
G Value stored in license module *pModule
H Random number
---------------------------------------------------------------------------------------------------
Examples
If the internal algorithm is A = B + C,
Then the call result is *p1 = *p2 + *p3.
For example: The internal algorithm is A = A + G; If *p1 = 0, then when returning you may guess the content of license module *p1 = *pModule. Though you cannot read the content of modules directly, you may determine the content by algorithm. If possible, you had better check the content with an algorithm, not only comparing it in the program.
---------------------------------------------------------------------------------------------------


User-defined Algorithm Calculate 2


API Prototype
long UniKey_Calculate2( WORD* pHandle ,
DWORD* pStartAddress ,
DWORD* pSeed ,
WORD* pRegA ,
WORD* pRegB ,
WORD* pRegC ,
WORD* pRegD ) ;

Description
Return the results of a calculation performed in UniKey, using input provided by the developer and the CALCULATE2 function.

Parameters
Parameter Meaning
*pHandle [in] Dongle handle
*pStartAddress [in] Start point of calculation
*pSeed [in] Seed Code (32-bit)
*p1 [in, out] Register A
*p2 [in, out] Register B
*p3 [in, out] Register C
*p4 [in, out] Register D

Return values
Marco Value Meaning
SUCCESS 0 Success
ERROR_UNIKEY_INVALID_ADDR_OR_SIZE 204 Read/Write address or length is wrong
ERROR_UNIKEY_NEED_OPEN 212 No logon dongle before operating dongle
ERROR_UNIKEY_AR_BAD_COMMAND 217 Arithmetic instruction Error
ERROR_UNIKEY_AR_UNKNOWN_OPCODE 218 Arithmetic operator Error
ERROR_UNIKEY_AR_WRON_GBEGIN 219 Const number can't use on first arithmetic instruction
ERROR_UNIKEY_AR_WRONG_END 220 Const number can't use on last arithmetic instruction
ERROR_UNIKEY_AR_VALUE_OVERFLOW 221 Const number > 63


When performing calculation 2, the initial values of register E, F, G and H are the return values of seed code *pSeed, to make it simple, UNIKEY calls function SEED with seed code *pSeed, and writes the return values to register E, F, G and H for the next operation.
--------------------------------------------------------------------------------------------------

Internal Register Meaning
E Seed Result 1
F Seed Result 2
G Seed Result 3
H Seed Result 4

 

User-defined Algorithm Calculate 3


API Prototype
long UniKey_Calculate3( WORD* pHandle ,
DWORD* pStartAddress ,
DWORD* pModule ,
WORD* pRegA ,
WORD* pRegB ,
WORD* pRegC ,
WORD* pRegD ) ;

Description
Return results of a calculation performed in UniKey, using input provided by the developer and the CALCULATE3 function.

Parameters
Parameter Meaning
*pHandle [in] Dongle handle
*pStartAddress [in] Start point of calculation
*pModule [in] License module number
*pRegA [in, out] Register A
*pRegB [in, out] Register B
*pRegC [in, out] Register C
*pRegD [in, out] Register D

Return value
Marco Value Meaning
SUCCESS 0 Success
ERROR_UNIKEY_INVALID_ADDR_OR_SIZE 204 Read/Write address or length is wrong
ERROR_UNIKEY_NEED_OPEN 212 No logon dongle before operating dongle
ERROR_UNIKEY_AR_BAD_COMMAND 217 Arithmetic instruction Error
ERROR_UNIKEY_AR_UNKNOWN_OPCODE 218 Arithmetic operator Error
ERROR_UNIKEY_AR_WRON_GBEGIN 219 Const number can't use on first arithmetic instruction
ERROR_UNIKEY_AR_WRONG_END 220 Const number can't use on last arithmetic instruction
ERROR_UNIKEY_AR_VALUE_OVERFLOW 221 Const number > 63


When performing calculation 3, the initial values of register E, F, G and H are the content of license module *lp2 and *lp2+1/2/3.
------------------------------------------------------------------------------------------------------

Internal Register Meaning
E Value in license module *lp2
F Value in license module (*lp2 + 1)
G Value in license module (*lp2 + 2)
H Value in license module (*lp2 + 3)
---------------------------------------------------------------------------------------------------
Examples
When calls calculation 3 with *pModule = 0, the initial values of register E, F, G and H are:
E = Value of license module 0
F = Value of license module 1
G = Value of license module 2
F = Value of license module 3
Note: The address will return to “0” when the license module address call exceeds 128. For example: Calculation 3 with *pModule = 126, the initial values of register E, F, G and H are:
E = Value of license module 126
F = Value of license module 127
G = Value of license module 0
H = Value of license module 1
---------------------------------------------------------------------------------------------------


UniKey_Calculate is called when you want to perform the algorithm you have written inside the UniKey dongle. For example, you have written a formula into the dongle, you can call UniKey_Calculate to perform the algorithms and get the return of the formula.
---------------------------------------------------------------------------------------------------
<a _fcknotitle="true" href="Category:UniKey_APIs">UniKey_APIs</a>

Retrieved from "https://esecutech.com/wiki/index.php?title=UniKey_API_Reference_for_C_Language&oldid=271"