UniKey API Reference for C Language: Difference between revisions
| Line 1,258: | Line 1,258: | ||
<br> | <br> | ||
=== User- | === User-Defined Algorithm Calculate 2 === | ||
'''API Prototype''' | '''API Prototype''' | ||
Revision as of 16:27, 12 July 2016
UniKey API Reference
A WORD is defined to be a 16-bit unsigned integer, while a DWORD is a 32-bit unsigned integer. These should be defined as types of that size regardless of platform.
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 used to start a UniKey session.
Parameters
| Parameter | Description |
|---|---|
| *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 |
| [out] Number of dongles attached, useless for UniKey STD |
Return values
| Result | Value | Description |
|---|---|---|
| SUCCESS | 0 | Success |
| ERROR_UNIKEY_NOT_FOUND | 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 | Description |
|---|---|
| *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 |
| [out] Number of dongles attached , useless for UniKey STD |
Return values
| Result | Value | Meaning |
|---|---|---|
| SUCCESS | 0 | Success |
| ERROR_UNIKEY_NOMORE | 214 | No more dongles found |
| ERROR_UNIKEY_NEED_FIND | 215 | Find needs to be called before Find_Next |
Log on to 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
Log in to a UniKey dongle with specified passwords. This API should be called in the commercial software in order to improve security.
Parameters
| Parameter | Description |
|---|---|
| *pPassword1 | [in] Password 1 |
| *pPassword2 | [in] Password 2 |
| *pHandle | [out] Dongle handle |
Return values
| Result | Value | Description |
|---|---|---|
| SUCCESS | 0 | Success |
| ERROR_UNIKEY_NOT_FOUND | 200 | No UniKey dongle |
| ERROR_UNIKEY_INVALID_PASSWORD | 201 | Found UniKey dongle, but basic passwords (password 1 and 2) are incorrect |
| ERROR_UNIKEY_INVALID_PASSWORD_OR_ID | 202 | Wrong password or UniKey HID |
Log on to 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
Log in to a UniKey dongle in vendor mode with specified passwords. This API helps software vendors to log in to the UniKey dongle in vendor mode, and get full permissions to the 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 password 3 or 4 is wrong, while password 1 and 2 is correct, the dongle is then logged on in user mode automatically.
Parameters
| Parameter | Description |
|---|---|
| *pPassword1 | [in] Password 1 |
| *pPassword2 | [in] Password 2 |
| *pPassword3 | [in] Password 3 |
| *pPassword4 | [in] Password 4 |
| *pHandle | [out] Dongle handle |
Return values
| Result | Value | Description |
|---|---|---|
| SUCCESS | 0 | Success |
| ERROR_UNIKEY_NOT_FOUND | 200 | No UniKey dongle |
| ERROR_UNIKEY_INVALID_PASSWORD | 201 | Found UniKey dongle, but basic passwords (password 1 and 2) are incorrect |
| ERROR_UNIKEY_INVALID_PASSWORD_OR_ID | 202 | Wrong password or UniKey HID |
Log off the UniKey dongle
API Prototype
long UniKey_Logoff(WORD* pHandle);
Description
Log off a UniKey dongle with a specific handle; this API should be called at the end of a UniKey session.
Parameters
| Parameter | Description |
|---|---|
| *pHandle | [in] Dongle handle |
Return values
| Result | Value | Description |
|---|---|---|
| SUCCESS | 0 | Success |
| ERROR_UNIKEY_NOT_FOUND | 200 | No UniKey dongle |
| ERROR_UNIKEY_NEED_OPEN | 212 | Need to log on to a dongle before running |
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.
This functions return value will help to indicate the type of the UniKey dongle.
| Type | Code |
|---|---|
| UNIKEY_TYPE_TIME | 101 |
| UNIKEY_TYPE_PRO | 102 |
| UNIKEY_TYPE_STD | 103 |
Parameters
| Parameter | Description |
|---|---|
| *pHandle | [in] Dongle handle |
| *type | [out] The value indicating the type of your UniKey dongle |
Return values
| Result | Value | Description |
|---|---|---|
| SUCCESS | 0 | Success |
| ERROR_UNIKEY_GET_TYPE | 256 | 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 memory; this API needs to be called after logging in to a UniKey dongle.
Parameters
| Parameter | Description |
|---|---|
| *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
| Result | Value | Description |
|---|---|---|
| SUCCESS | 0 | Success |
| ERROR_UNIKEY_INVALID_ADDR_OR_SIZE | 204 | Read/Write address is incorrect or invalid length |
| ERROR_UNIKEY_READ_MEMORY | 207 | Read Error |
| ERROR_UNIKEY_NEED_OPEN | 212 | Need to log on to a dongle before running |
Write to UniKey dongle memory
API Prototype
long UniKey_Write_Memory(WORD* pHandle, WORD* pStartAddress, WORD* pBufferLength, BYTE* pBuffer);
Description
Write data into memory; this API needs to be called after logging on to a UniKey dongle.
Parameters
| Parameter | Description |
|---|---|
| *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
| Result | Value | Description |
|---|---|---|
| SUCCESS | 0 | Success |
| ERROR_UNIKEY_INVALID_ADDR_OR_SIZE | 204 | Read/Write address is incorrect or invalid length |
| ERROR_UNIKEY_WRITE_MEMORY | 207 | Write Error |
| ERROR_UNIKEY_NEED_OPEN | 212 | Need to log on to a dongle before running |
| ERROR_UNIKEY_VERIFY_ADV_PASSWORD | 223 | Advanced passwords (password 3 and 4) not verified |
To write the last 2k memory (for 2048 – 4096), you need to verify all 4 passwords (vendor mode) to obtain the requisite permission.
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
Generates random numbers from the dongle.
Parameters
| Parameter | Description |
|---|---|
| *pHandle | [in] Dongle handle |
| *pReturn1 | [out] Random number |
| *pReturn2 | [out] Random number |
| *pReturn3 | [out] Random number |
| *pReturn4 | [out] Random number |
Return values
| Result | Value | Description |
|---|---|---|
| SUCCESS | 0 | Success |
| ERROR_UNIKEY_RANDOM | 209 | Random number error |
| ERROR_UNIKEY_NEED_OPEN | 212 | Need to log on to a dongle before running |
UNIKEY_RANDOM is to generate a random number inside the dongle. The UniKey dongle computation 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 the UniKey dongle’s password.
Parameters
| Parameter | Description |
|---|---|
| *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
| Result | Value | Description |
|---|---|---|
| SUCCESS | 0 | Success |
| ERROR_UNIKEY_SEED | 210 | Seed code error |
| ERROR_UNIKEY_NEED_OPEN | 212 | Need to log on to a dongle before running |
UniKey_Seed generate a set of seed codes; all of these seed codes are based on the password. providing another method to verify passwords and check if a dongle has been inserted. Apart from this, the seed codes can be used in other computations, for example, you can use the seed returned as a 64-bit encryption key.
Write Software ID
API Prototype
long UniKey_Write_SoftID(WORD* pHandle, DWORD* pSoftID);
Description
Write the vendor-defined software ID.
Parameters
| Parameter | Description |
|---|---|
| *pHandle | [in] Dongle handle |
| *pSoftID | [in] Software ID |
Return values
| Result | Value | Description |
|---|---|---|
| SUCCESS | 0 | Success |
| ERROR_UNIKEY_SET_SOFTID | 203 | Set software ID error |
| ERROR_UNIKEY_NEED_OPEN | 212 | Need to log on to a dongle before running |
You need to verify all 4 passwords (vendor mode) to write the software ID to the dongle.
Read Software ID
API Prototype
long UniKey_Read_SoftID(WORD* pHandle, DWORD* pSoftID);
Description
Read the user-defined software ID.
Parameters
| Parameter | Description |
|---|---|
| *pHandle | [in] Dongle handle |
| *pSoftID | [out] Software ID |
Return values
| Result | Value | Description |
|---|---|---|
| SUCCESS | 0 | Success |
| ERROR_UNIKEY_NEED_OPEN | 212 | Need to log on to a dongle before running |
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 | Description |
|---|---|
| *pHandle | [in] Dongle handle |
| *pModule | [in] License module number |
| *pValue | [in] License module unit value |
| *pDecrease | [in] Decrement attribute (1 = allowed, 0 = not allowed) |
Return values
| Result | Value | Description |
|---|---|---|
| SUCCESS | 0 | Success |
| ERROR_UNIKEY_INVALID_ADDR_OR_SIZE | 202 | Read/Write address is incorrect or invalid length |
| ERROR_UNIKEY_NEED_OPEN | 212 | Need to log on to a dongle before running |
| ERROR_UNIKEY_MODULE | 216 | License module error |
A successful operation will result in license module unit number *pModule storing value *pValue, and the Decrement attribute set to "0" or "1".
You need to 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 | Description |
|---|---|
| *pHandle | [in] Dongle handle |
| *pModule | [in] Module Number |
| *pValue | [out] Return the value in module |
Return values
| Result | Value | Description |
|---|---|---|
| SUCCESS | 0 | Success |
| ERROR_UNIKEY_INVALID_ADDR_OR_SIZE | 202 | Read/Write address is incorrect or invalid length |
| ERROR_UNIKEY_NEED_OPEN | 212 | Need to log on to a dongle before running |
| ERROR_UNIKEY_MODULE | 216 | License module error |
You need to 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 | Description |
|---|---|
| *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
| Result | Value | Description |
|---|---|---|
| SUCCESS | 0 | Success |
| ERROR_UNIKEY_INVALID_ADDR_OR_SIZE | 202 | Read/Write address is incorrect or invalid length |
| ERROR_UNIKEY_NEED_OPEN | 212 | Need to log on to a dongle before running |
| ERROR_UNIKEY_MODULE | 216 | License module error |
A successful operation will result in *pValue having value from Validity (1 = license module value is not zero), and *pDecrease having value from the Decrement attribute (1 = license module can be decreased). The value of a license module cannot be read directly, and it is invisible to end users.
UniKey_Set_Module and UniKey_Check_Module provide an easy way to implement software limitations. For example, if you want to set software to only be executed 3 times, you can call UniKey_Set_Module to set a license module (let us say license module 0) as 3. And, during 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 the 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 modules in the UniKey dongle. Let us say that 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 and B, you only need to enable license module 0 and 1, and leave 2 and 3 as zero. So now only function module A and B can be executed. If the customer buys additional functions, you can use the UniKey Remote Updater tool to update the dongle as needed remotely.
Write Arithmetic
API Prototype
long UniKey_Write_Arithmetic(WORD* pHandle, WORD* pStartAddress, BYTE* pBuffer);
Description
Write user-defined mathematical algorithms.
Parameters
| Parameter | Description |
|---|---|
| *pHandle | [in] Dongle handle |
| *pStartAddress | [in] Offset of first instruction |
| *pBuffer | [in] Pointer to the algorithm command string |
Return values
| Result | Value | Description |
|---|---|---|
| SUCCESS | 0 | Success |
| ERROR_UNIKEY_INVALID_ADDR_OR_SIZE | 204 | Read/Write address is incorrect or invalid length |
| ERROR_UNIKEY_NEED_OPEN | 212 | Need to log on to a dongle before running |
| ERROR_UNIKEY_AR_BAD_COMMAND | 217 | Arithmetic instruction error |
| ERROR_UNIKEY_AR_UNKNOWN_OPCODE | 218 | Arithmetic operator error |
| ERROR_UNIKEY_AR_WRONG_BEGIN | 219 | Constant numbers can't be used on first arithmetic instruction |
| ERROR_UNIKEY_AR_WRONG_END | 220 | Constant numbers can't be used on last arithmetic instruction |
| ERROR_UNIKEY_AR_VALUE_OVERFLOW | 221 | Constant numbers > 63 will cause an overflow |
A successful operation will result in a user-defined algorithm containing 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 on the software vendor side. For example, if you have a serial number generator 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 the UniKey, using input provided by the developer and the CALCULATE1 function.
Parameters
| Parameter | Description |
|---|---|
| *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 values
| Result | Value | Description |
|---|---|---|
| SUCCESS | 0 | Success |
| ERROR_UNIKEY_INVALID_ADDR_OR_SIZE | 204 | Read/Write address is incorrect or invalid length |
| ERROR_UNIKEY_NEED_OPEN | 212 | Need to log on to a dongle before running |
| ERROR_UNIKEY_AR_BAD_COMMAND | 217 | Arithmetic instruction error |
| ERROR_UNIKEY_AR_UNKNOWN_OPCODE | 218 | Arithmetic operator error |
| ERROR_UNIKEY_AR_WRONG_BEGIN | 219 | Constant numbers can't be used on first arithmetic instruction |
| ERROR_UNIKEY_AR_WRONG_END | 220 | Constant numbers can't be used on last arithmetic instruction |
| ERROR_UNIKEY_AR_VALUE_OVERFLOW | 221 | Constant numbers > 63 will cause an overflow |
When the calculation starts, the values of other internal registers are listed in the table below.
E and F is the bytewise reversed hardware ID. For example, if the hardware is 0x12345678 (in hex), then E will be 0x7856 and F will be 0x3412.
| Internal Register | Description |
|---|---|
| E | High-order byte of reversed hardware ID |
| F | Low-order byte 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
The internal algorithm is A = A + G; if *p1 = 0, then you may guess the result is the license module such that *p1 = G = *pModule
Though you cannot read the content of modules directly, you can determine the content by an algorithm. If possible, it would be best to also check this content with an algorithm, and not only compare 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 the UniKey, using input provided by the developer and the CALCULATE2 function.
Parameters
| Parameter | Description |
|---|---|
| *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
| Result | Value | Description |
|---|---|---|
| SUCCESS | 0 | Success |
| ERROR_UNIKEY_INVALID_ADDR_OR_SIZE | 204 | Read/Write address is incorrect or invalid length |
| ERROR_UNIKEY_NEED_OPEN | 212 | Need to log on to a dongle before running |
| ERROR_UNIKEY_AR_BAD_COMMAND | 217 | Arithmetic instruction error |
| ERROR_UNIKEY_AR_UNKNOWN_OPCODE | 218 | Arithmetic operator error |
| ERROR_UNIKEY_AR_WRON_GBEGIN | 219 | Constant numbers can't be used on first arithmetic instruction |
| ERROR_UNIKEY_AR_WRONG_END | 220 | Constant numbers can't be used on last arithmetic instruction |
| ERROR_UNIKEY_AR_VALUE_OVERFLOW | 221 | Constant numbers > 63 will cause an overflow |
When using calculate 2, the initial values of register E, F, G and H are the return values of seed code *pSeed, to make it simple, the 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 | Description |
|---|---|
| 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 the UniKey, using input provided by the developer and the CALCULATE3 function.
Parameters
| Parameter | Description |
|---|---|
| *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 values
| Result | Value | Description |
|---|---|---|
| SUCCESS | 0 | Success |
| ERROR_UNIKEY_INVALID_ADDR_OR_SIZE | 204 | Read/Write address is incorrect or invalid length |
| ERROR_UNIKEY_NEED_OPEN | 212 | Need to log on to a dongle before running |
| ERROR_UNIKEY_AR_BAD_COMMAND | 217 | Arithmetic instruction error |
| ERROR_UNIKEY_AR_UNKNOWN_OPCODE | 218 | Arithmetic operator error |
| ERROR_UNIKEY_AR_WRON_GBEGIN | 219 | Constant numbers can't be used on first arithmetic instruction |
| ERROR_UNIKEY_AR_WRONG_END | 220 | Constant numbers can't be used on last arithmetic instruction |
| ERROR_UNIKEY_AR_VALUE_OVERFLOW | 221 | Constant numbers > 63 will cause an overflow |
When using calculate 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 | Description |
|---|---|
| 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 calling 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 algorithm and get the return value of the formula.
Decrease a License Module
API Prototype
long UniKey_Module_Decrease(WORD* pHandle, WORD* pModule);
Description
Decrease the value in a specified UniKey license module by "1".
Parameters
| Parameter | Description |
|---|---|
| *pHandle | [in] Dongle handle |
| *pModule | [in] License module number |
Return values
| Result | Value | Description |
|---|---|---|
| SUCCESS | 0 | Success |
| ERROR_UNIKEY_INVALID_ADDR_OR_SIZE | 204 | Read/Write address is incorrect or invalid length |
| ERROR_UNIKEY_NEED_OPEN | 212 | Need to log on to a dongle before running |
| ERROR_UNIKEY_MODULE | 216 | License module error |
Please call UniKey_Check_Module to check if the license module is valid first.
Generate a New Password
API Prototype
long UniKey_Generate_New_Password(WORD* pHandle, DWORD* pSeed, WORD* pPassword1, WORD* pPassword2, WORD* pPassword3, WORD* pPassword4);
Description
Generate a new password via a seed code; the mapping from the seed code to the password is a one-way function. Without the seed, you cannot generate the same password.
Parameters
| Parameter | Description |
|---|---|
| *pHandle | [in] Dongle handle |
| *pSeed | [in] Seed code (32-bit) |
| *pPassword1 | [out] New password 1 |
| *pPassword2 | [out] New password 2 |
| *pPassword3 | [out] New password 3 |
| *pPassword4 | [out] New password 4 |
Return values
| Result | Value | Description |
|---|---|---|
| SUCCESS | 0 | Success |
| ERROR_UNIKEY_NEED_OPEN | 212 | Need to log on to a dongle before running |
| ERROR_UNIKEY_VERIFY_ADV_PASSWORD | 223 | Advanced passwords (passwords 3 and 4) not verified |
| ERROR_UNIKEY_GENERATE_NEW_PASSWORD | 225 | Error generating new password |
A file recording the new seed and passwords will be created in the working path, helping the software vendor to record everything. The passwords can be distributed to ordinary developers!
- The dongle will automatically log off after a new set of passwords have been generated.
- The dongle will be fully formatted when a new password is generated.
- A file including the new passwords and seed will be created in the working directory.
Generate a New Encryption Key
API Prototype
long UniKey_Generate_Key(WORD* pHandle, DWORD* pKeyNumber);
Description
Generate a new key in the specific key storage.
Parameters
| Parameter | Description |
|---|---|
| *pHandle | [in] Dongle handle |
| *pKeyNumber | [in] Key storage number |
Return values
| Result | Value | Description |
|---|---|---|
| SUCCESS | 0 | Success |
| ERROR_UNIKEY_NEED_OPEN | 212 | Need to log on to a dongle before running |
| ERROR_UNIKEY_INVALID_KEY_STORE | 224 | Wrong key storage number |
- This function will delete the original key in the key storage, and generate a new key.
- The data encrypted by the old key cannot be decrypted by the new key.
- Each key is 128-bits long.
Generate a New Encryption Key via Seed
API Prototype
long UniKey_Generate_Key_Via_Seed(WORD* pHandle, DWORD* pKeyNumber, WORD pSeed1, WORD pSeed2, WORD pSeed3, WORD pSeed4);
Description
Generate a new key in the specific key storage via a seed.
Parameters
| Parameter | Description |
|---|---|
| *pHandle | [in] Dongle handle |
| *pKeyNumber | [in] Key storage number |
| *pSeed1 | [in] Seed 1 |
| *pSeed2 | [in] Seed 2 |
| *pSeed3 | [in] Seed 3 |
| *pSeed4 | [in] Seed 4 |
Return values
| Result | Value | Description |
|---|---|---|
| SUCCESS | 0 | Success |
| ERROR_UNIKEY_NEED_OPEN | 212 | Need to log on to a dongle before running |
| ERROR_UNIKEY_INVALID_KEY_STORE | 224 | Wrong key storage number |
- This function will delete the original key in the key storage, and generate a new key via seed.
- The data encrypted by the old key cannot be decrypted by the new key.
- Each key is 128-bit long.
Encrypt the Buffer with a Specific Encryption Key
API Prototype
long UniKey_Encrypt(WORD* pHandle, DWORD* pBufferLength, DWORD* pKeyNumber, BYTE* pBuffer);
Description
Encrypt an amount of memory with a key. The length of data must be a multiple of 8.
Parameters
| Parameter | Meaning |
|---|---|
| *pHandle | [in] Dongle handle |
| *pBufferLength | [in] Number of bytes to encrypt |
| *pKeyNumber | [in] Key storage number |
| *pBuffer | [in] Pointer to the data to be encrypted |
| [out] Pointer to the encrypted data |
Return values
| Result | Value | Description |
|---|---|---|
| SUCCESS | 0 | Success |
| ERROR_UNIKEY_NEED_OPEN | 212 | Need to log on to a dongle before running |
| ERROR_UNIKEY_INVALID_KEY_STORE | 224 | Wrong key storage number |
| ERROR_UNIKEY_ENCRYPT_FAILED | 228 | Could not encrypt data |
This function only performs an encryption operation, no compression functions are involved.
Decrypt the Buffer with a Specific Encryption Key
API Prototype
long UniKey_Decrypt(WORD* pHandle, DWORD* pBufferLength, DWORD* pKeyNumber, BYTE* pBuffer);
Description
Encrypt an amount of memory with a key. The length of data must be a multiple of 8.
Parameters
| Parameter | Meaning |
|---|---|
| *pHandle | [in] Dongle handle |
| *pBufferLength | [in] Number of bytes to encrypt |
| *pKeyNumber | [in] Key storage number |
| *pBuffer | [in] Pointer to the data to be decrypted |
| [out] Pointer to the decrypted data |
Return values
| Result | Value | Description |
|---|---|---|
| SUCCESS | 0 | Success |
| ERROR_UNIKEY_NEED_OPEN | 212 | Need to log on to a dongle before running |
| ERROR_UNIKEY_INVALID_KEY_STORE | 224 | Wrong key storage number |
| ERROR_UNIKEY_DECRYPT_FAILED | 229 | Could not decrypt data |
Please use the key that was used to encrypt the data to decrypt the data, otherwise you cannot properly decrypt the data.
UniKey_Encrypt and UniKey_Decrypt offer a basic 128-bit encryption/decryption operation based on UniKey’s hardware. You can call these functions when an encryption or decryption operation is needed. For better security, you can encrypt a credential before saving it into the UniKey’s memory.
Make an MD5 Digest for Certain Content
API Prototype
long UniKey_MD5(WORD* pHandle, DWORD* pBufferLength, DWORD* pType, BYTE* pBuffer);
Description
Make an MD5 digest of content or data.
Parameters
| Parameter | Meaning |
|---|---|
| *pHandle | [in] Dongle handle |
| *pBufferLength | [in] Number of bytes to MD5 |
| *pBuffer | [in] Pointer to the data to be digested |
| [out] Pointer to the digested data |
Return values
| Result | Value | Description |
|---|---|---|
| SUCCESS | 0 | Success |
| ERROR_UNIKEY_NEED_OPEN | 212 | Need to log on to a dongle before running |
Read UpdateTag
API Prototype
long UniKey_Read_UpdateTag(WORD* pHandle, DWORD* pUpdateTag);
Description
Read UpdateTag from a specific dongle
Parameters
| Parameter | Description |
|---|---|
| *pHandle | [in] Dongle handle |
| *pUpdateTag | [out] UpdateTag |
Return values
| Result | Value | Description |
|---|---|---|
| SUCCESS | 0 | Success |
| ERROR_UNIKEY_NEED_OPEN | 212 | Need to log on to a dongle before running |
| ERROR_UNIKEY_READ_UPDATETAG | 226 | Read UpdateTag error |
Write UpdateTag
API Prototype
long UniKey_Write_UpdateTag(WORD* pHandle, DWORD* pUpdateTag);
Description
Write UpdateTag into a specific dongle.
Parameters
| Parameter | Description |
|---|---|
| *pHandle | [in] Dongle handle |
| *pUpdateTag | [in] UpdateTag |
Return values
| Result | Value | Description |
|---|---|---|
| SUCCESS | 0 | Success |
| ERROR_UNIKEY_NEED_OPEN | 212 | Need to log on to a dongle before running |
| ERROR_UNIKEY_WRITE_UPDATETAG | 227 | Write UpdateTag error |
UniKey_Read_UpdateTag APIs give software vendors an easy method to identify if the UniKey dongle needs to be updated. When distributing software, software vendors may use the UpdateTag as an ID which shows if the dongle needs to be updated or has been updated. You can also use this tag as a tracking ID for each update.
Get UniKey Library Version
API Prototype
long UniKey_Get_Version(WORD* pHandle, DWORD* pVersion);
Description
Get the current UniKey library version.
Parameters
| Parameter | Description |
|---|---|
| *pHandle | [in] Dongle handle |
| *pVersion | [out] UniKey library version |
UniKey Time API Reference
Get UniKey Time
API Prototype
long UniKey_Get_Time(WORD* pHandle, DWORD* pYear, DWORD* pMonth, WORD* pDay, WORD* pHour, WORD* pMinute, WORD* pSecond);
Description
Get the time from the UniKey Time’s real-time clock.
Parameters
| Parameter | Description |
|---|---|
| *pHandle | [in] Dongle handle |
| *pYear | [out] Year (input or output is 10, which refers to 2010) |
| *pMonth | [out] Month |
| *pDay | [out] Day |
| *pHour | [out] Hour |
| *pMinute | [out] Minute |
| *pSecond | [out] Second |
Return values
| Result | Value | Description |
|---|---|---|
| SUCCESS | 0 | Success |
| ERROR_UNIKEY_NEED_OPEN | 212 | Need to log on to a dongle before running |
| ERROR_UNIKEY_READ_TIME | 230 | Get UniKey time error |
Calling UniKey_Check_Time can check if the dongle is a UniKey Time model. If ERROR_UNIKEY_READ_TIME is returned, then the dongle is not a UniKey Time.
Set UniKey Time
API Prototype
long UniKey_Set_Time(WORD* pHandle, DWORD* pYear, DWORD* pMonth, WORD* pDay, WORD* pHour, WORD* pMinute, WORD* pSecond);
Description
Set the time on the UniKey Time’s clock.
Parameters
| Parameter | Description |
|---|---|
| *pHandle | [in] Dongle handle |
| *pYear | [in] Year (input or output is 10, which refers to 2010) |
| *pMonth | [in] Month |
| *pDay | [in] Day |
| *pHour | [in] Hour |
| *pMinute | [in] Minute |
| *pSecond | [in] Second |
Return values
| Result | Value | Description |
|---|---|---|
| SUCCESS | 0 | Success |
| ERROR_UNIKEY_NEED_OPEN | 212 | Need to log on to a dongle before running |
| ERROR_UNIKEY_READ_TIME | 230 | Get UniKey time error |
You need to verify all 4 passwords (vendor mode) to set the time of the UniKey Time's internal clock.
Set UniKey Time by Host’s Clock
API Prototype
long UniKey_Set_Time_Now(WORD* pHandle);
Description
Set the time of the UniKey Time’s real-time clock to the host computer’s clock.
Parameters
| Parameter | Description |
|---|---|
| *pHandle | [in] Dongle handle |
Return values
| Result | Value | Description |
|---|---|---|
| SUCCESS | 0 | Success |
| ERROR_UNIKEY_NEED_OPEN | 212 | Need to log on to a dongle before running |
| ERROR_UNIKEY_WRITE_TIME | 231 | Set UniKey time error |
Erase Real Time Module
API Prototype
long UniKey_Erase_Time_Module(WORD* pHandle, DWORD* pModule);
Description
Erase/Reset a real-time module, and all the information in the module will be erased including start, and end or duration.
Parameters
| Parameter | Description |
|---|---|
| *pHandle | [in] Dongle handle |
| *pModule | [in] Real-time module number (0-15) |
Return values
| Result | Value | Description |
|---|---|---|
| SUCCESS | 0 | Success |
| ERROR_UNIKEY_NEED_OPEN | 212 | Need to log on to a dongle before running |
| ERROR_UNIKEY_WRITE_TIME | 231 | Set UniKey time error |
You need to verify all 4 passwords (vendor mode) to reset a module. If a real-time module’s write-once flag is enabled, only the first START_TIME call works. Successive START_TIME calls will return an error until this module is reset.
Set a Real Time Module’s Start Time
API Prototype
long UniKey_Set_Time_Module_Start_Time(WORD* pHandle, DWORD* pModule, WORD* pYear, WORD* pMonth, WORD* pDay, WORD* pHour);
Description
Set a real-time module’s start time.
Parameters
| Parameter | Description |
|---|---|
| *pHandle | [in] Dongle handle |
| *pModule | [in] Real-time module number (0-15) |
| *pYear | [in] Year (input or output is 10, which refers to 2010) |
| *pMonth | [in] Month |
| *pDay | [in] Day |
| *pHour | [in] Hour |
Return values
| Result | Value | Description |
|---|---|---|
| SUCCESS | 0 | Success |
| ERROR_UNIKEY_NEED_OPEN | 212 | Need to log on to a dongle before running |
| ERROR_UNIKEY_WRITE_TIME_MODULE | 231 | Set UniKey time error |
| ERROR_UNIKEY_TIME_MODULE_NOT_NULL | 234 | The real-time module is not null, this error is returned when the 'write once' flag is set |
The write-once flag is very useful for setting the start for a real-time module. If the write-once flag is set, only the first START_TIME call can set the start time for a module; all successive START_TIME calls will not work and return an ERROR_UNIKEY_TIME_MODULE_NOT_NULL. Software vendors may use this flag when the start for a module is not clear.
Set a Real Time Module’s Start Time by the UniKey's Internal Clock
API Prototype
long UniKey_Set_Time_Module_Start_Time_Now(WORD* pHandle, DWORD* pModule);
Description
Set a real-time module’s start time as the current time in the UniKey's internal clock.
Parameters
| Parameter | Description |
|---|---|
| *pHandle | [in] Dongle handle |
| *pModule | [in] Real-time module number (0-15) |
Return values
| Result | Value | Description |
|---|---|---|
| SUCCESS | 0 | Success |
| ERROR_UNIKEY_NEED_OPEN | 212 | Need to log on to a dongle before running |
| ERROR_UNIKEY_WRITE_TIME_MODULE | 231 | Set UniKey time error |
| ERROR_UNIKEY_TIME_MODULE_NOT_NULL | 234 | The real-time module is not null, this error is returned when the 'write once' flag is set |
Set a Real Time Module’s Start Time by Host’s Clock
API Prototype
long UniKey_Set_Time_Module_Start_Time_Now_PC(WORD* pHandle, DWORD* pModule);
Description
Set a real time module’s start time as the current time of the host computer.
Parameters
| Parameter | Description |
|---|---|
| *pHandle | [in] Dongle handle |
| *pHandle | [in] Real-time module number (0-15) |
Return values
| Result | Value | Description |
|---|---|---|
| SUCCESS | 0 | Success |
| ERROR_UNIKEY_NEED_OPEN | 212 | Need to log on to a dongle before running |
| ERROR_UNIKEY_WRITE_TIME_MODULE | 231 | Set UniKey time error |
| ERROR_UNIKEY_TIME_MODULE_NOT_NULL | 234 | The real-time module is not null, this error is returned when the 'write once' flag is set |
Set a Real Time Module’s End Time
API Prototype
long UniKey_Set_Time_Module_End_Time(WORD* pHandle, DWORD* pModule, WORD* pYear, WORD* pMonth, WORD* pDay, WORD* pHour);
Description
Set a real-time module’s end time.
Parameters
| Parameter | Description |
|---|---|
| *pHandle | [in] Dongle handle |
| *pHandle | [in] Real-time module number (0-15) |
| *pYear | [in] Year (input or output is 10, which refers to 2010) |
| *pMonth | [in] Month |
| *pDay | [in] Day |
| *pHour | [in] Hour |
Return values
| Result | Value | Description |
|---|---|---|
| SUCCESS | 0 | Success |
| ERROR_UNIKEY_NEED_OPEN | 212 | Need to log on to a dongle before running |
| ERROR_UNIKEY_WRITE_TIME_MODULE | 231 | Set UniKey time error |
Set a Real Time Module’s Duration
API Prototype
long UniKey_Set_Time_Module_Duration(WORD* pHandle, DWORD* pModule, DWORD* pDay, WORD* pHour);
Description
Set the duration for a specific real-time module. The total duration is (*pDay) * 24 + (*pHour) in hours.
Parameters
| Parameter | Description |
|---|---|
| *pHandle | [in] Dongle handle |
| *pModule | [in] Real-time module number (0-15) |
| *pDay | [in] Number of days |
| *pHour | [in] Number of hours |
Return values
| Result | Value | Description |
|---|---|---|
| SUCCESS | 0 | Success |
| ERROR_UNIKEY_NEED_OPEN | 212 | Need to log on to a dongle before running |
| ERROR_UNIKEY_WRITE_TIME_MODULE | 231 | Set UniKey time error |
You need to verify all 4 passwords (vendor mode) to set the duration for a real-time module.
Check a UniKey Time License module
API Prototype
long UniKey_Check_Time_Module(WORD* pHandle, DWORD* pModule, DWORD* pRemainDays, WORD* pYear, WORD* pMonth, WORD* pDay, WORD* pHour);
Description
Read the attributes of a specific UniKey Time license module.
Parameters
| Parameter | Description |
|---|---|
| *pHandle | [in] Dongle handle |
| *pModule | [in] License module Number |
| *pRemainDays | [out] Days remaining |
| *pYear | [in] Year (input or output is 10, which refers to 2010) |
| *pMonth | [in] Month |
| *pDay | [in] Day |
| *pHour | [in] Hour |
Return values
| Result | Value | Description |
|---|---|---|
| SUCCESS | 0 | Success |
| ERROR_UNIKEY_INVALID_ADDR_OR_SIZE | 204 | Read/Write address is incorrect or invalid length |
| ERROR_UNIKEY_NEED_OPEN | 212 | Need to log on to a dongle before running |
| ERROR_UNIKEY_MODULE | 216 | License module error |
A successful operation will result in *pValue having value from the validity of a license module (1 = license module value is not zero).
The value of a license module cannot be read out directly and it is invisible to end users.
Check a UniKey Time License Module Now
API Prototype
long UniKey_Check_Time_Module_Now(WORD* pHandle, DWORD* pModule, DWORD* pRemainDays, WORD* pRemainHours);
Description
Read the attributes of a specific UniKey Time license module Now.
Parameters
| Parameter | Description |
|---|---|
| *pHandle | [in] Dongle handle |
| *pModule | [in] License module number |
| *pRemainDays | [out] Days remaining |
| *pRemainHours | [out] Hours remaining |
Return values
| Result | Value | Description |
|---|---|---|
| SUCCESS | 0 | Success |
| ERROR_UNIKEY_INVALID_ADDR_OR_SIZE | 204 | Read/Write address is incorrect or invalid length |
| ERROR_UNIKEY_NEED_OPEN | 212 | Need to log on to a dongle before running |
| ERROR_UNIKEY_MODULE | 216 | License module error |
A successful operation will result in *pValue having value from the validity (1 = license module value is not zero).
The value of a license module cannot be read out directly and it is invisible to end users.
Check a UniKey Time License Module Now PC
API Prototype
long UniKey_Check_Time_Module_Now_PC(WORD* pHandle, DWORD* pModule, DWORD* pRemainDays, WORD* pRemainHours);
Description
Read the attributes of a specific UniKey Time license module Now PC.
Parameters
| Parameter | Description |
|---|---|
| *pHandle | [in] Dongle handle |
| *pModule | [in] License module number |
| *pRemainDays | [out] Days remaining |
| *pRemainHours | [out] Hours remaining |
Return values
| Result | Value | Description |
|---|---|---|
| SUCCESS | 0 | Success |
| ERROR_UNIKEY_INVALID_ADDR_OR_SIZE | 204 | Read/Write address is incorrect or invalid length |
| ERROR_UNIKEY_NEED_OPEN | 212 | Need to log on to a dongle before running |
| ERROR_UNIKEY_MODULE | 216 | License module error |
A successful operation will result in *pValue having value from the validity (1 = license module value is not zero).
The value of a license module cannot be read out directly and it is invisible to end users.
UniKey Drive API Reference
Initialize File System
API Prototype
long UniKey_FS_Init(WORD* pHandle, DWORD* PW1, DWORD* PW2, DWORD* PW3, DWORD* PW4);
Description
The user needs to call this function to initialize the file system before calling other file system related functions. The default password of the file system is "12345678", without quotations.
Parameters
| Parameter | Description |
|---|---|
| *pHandle | [in] Device handle |
| *PW1 | [in] Password 1 |
| *PW2 | [in] Password 2 |
| *PW3 | [in] Password 3 |
| *PW4 | [in] Password 4 |
Return values
| Result | Value | Description |
|---|---|---|
| SUCCESS | 0 | Success |
| ERROR_UNIKEY_INVALID_PASSWORD_OR_ID | 202 | Wrong password or UniKey HID |
Format the File System
API Prototype
long UniKey_FS_Format(WORD* pHandle);
Description
Format the file system.
Parameters
| Parameter | Description |
|---|---|
| *pHandle | [in] Device handle |
Return values
| Result | Value | Description |
|---|---|---|
| SUCCESS | 0 | Success |
| ERROR_UNIKEY_FS_FILE_EXIST | 245 | File already exists |
Note: The user needs to initialize the file system successfully before calling other file system related functions.
Create Files
API Prototype
long UniKey_FS_CreateFile(WORD* pHandle, BYTE* filename);
Description
Create files.
Parameters
| Parameter | Description |
|---|---|
| *pHandle | [in] Device handle |
| *filename | [in/out] Input/Output file name |
Note: a single backslash ("\") should be added before the name of the file.
Return values
| Result | Value | Description |
|---|---|---|
| SUCCESS | 0 | Success |
| ERROR_UNIKEY_FS_FILE_NAME | 240 | Wrong or invalid filename |
| ERROR_UNIKEY_FS_FILE_EXIST | 245 | File already exists |
| ERROR_UNIKEY_FS_ERR_SYS_UNINIT | 246 | The file system is not initialized |
Delete Files
API Prototype
long UniKey_FS_DeleteFile(WORD* pHandle, BYTE* filename);
Description
Delete files.
Parameters
| Parameter | Description |
|---|---|
| *pHandle | [in] Device handle |
| *filename | [in/out] Input/Output file name |
Return values
| Result | Value | Description |
|---|---|---|
| SUCCESS | 0 | Success |
| ERROR_UNIKEY_FS_NO_FILE | 241 | No such filename |
| ERROR_UNIKEY_FS_ERR_SYS_UNINIT | 246 | The file system is not initialized |
Open Files
API Prototype
long UniKey_FS_File_Open(WORD* pHandle, BYTE* filename);
Description
Open files.
Parameters
| Parameter | Description |
|---|---|
| *pHandle | [in] Device handle |
| *filename | [in] Input/Output file name |
Return values
| Result | Value | Description |
|---|---|---|
| SUCCESS | 0 | Success |
| ERROR_UNIKEY_FS_NO_FILE | 241 | No such filename |
Get System Space
API Prototype
long UniKey_FS_Get_Free_Size(WORD* pHandle, DWORD* usedsize, DWORD* freesize);
Description
Get occupied and free system space.
Parameters
| Parameter | Description |
|---|---|
| *pHandle | [in] Device handle |
| *usedsize | [out] System memory that is in use |
| *freesize | [out] Free system memory |
Return values
| Result | Value | Description |
|---|---|---|
| SUCCESS | 0 | Success |
Modify File Data
API Prototype
long UniKey_FS_File_Modify_Data(WORD* pHandle, DWORD* offset, DWORD* len, BYTE* buffer);
Description
Modify file data.
Parameters
| Parameter | Description |
|---|---|
| *pHandle | [in] Device handle |
| *offset | [in] Address to be modified |
| *len | [in] Length of data to be modified |
| *buffer | [in] Modified data |
Return values
| Result | Value | Description |
|---|---|---|
| SUCCESS | 0 | Success |
| ERROR_UNIKEY_FS_FILE_OFFSET | 242 | File offset error |
| ERROR_UNIKEY_FS_ERR_OPEN_FILE | 247 | Failed to open file |
Append Data to the End-Of-File
API Prototype
long UniKey_FS_File_Append_Data(WORD* pHandle, DWORD* len, BYTE* buffer);
Description
Append data to the end-of-file.
Parameters
| Parameter | Meaning |
|---|---|
| *pHandle | [in] Device handle |
| *len | [in] The length of the data to be appended |
| *buffer | [in] Data to append |
Return values
| Result | Value | Meaning |
|---|---|---|
| SUCCESS | 0 | Success |
| ERROR_UNIKEY_FS_NO_MEMORY | 244 | Not enough free memory |
Read File Data
API Prototype
longUniKey_FS_File_Read_Data(WORD* pHandle, DWORD* offset, DWORD* len, BYTE* buffer);
Description
Read file data.
Parameters
| Parameter | Description |
|---|---|
| *pHandle | [in] Device handle |
| *offset | [in] Read address |
| *len | [in] Length of data to be read |
| *buffer | [out] Read data |
Return values
| Result | Value | Description |
|---|---|---|
| SUCCESS | 0 | Success |
| ERROR_UNIKEY_FS_FILE_OFFSET | 242 | File offset error |
| ERROR_UNIKEY_FS_ERR_OPEN_FILE | 247 | Failed to open file |
Close Files
API Prototype
long UniKey_FS_File_Close(WORD* pHandle, BYTE* filename);
Description
Close files.
Parameters
| Parameter | Description |
|---|---|
| *pHandle | [in] Device handle |
| *filename | [in] Filename |
Return values
| Result | Value | Description |
|---|---|---|
| SUCCESS | 0 | Success |
Get File List
API Prototype
long UniKey_FS_File_Get_List(WORD* pHandle, DWORD* filecount, BYTE* filelist);
Description
Get list of files on the UniKey Drive.
Parameters
| Parameter | Description |
|---|---|
| *pHandle | [in] Device handle |
| *filecount | [out] The number of files |
| *filelist | [out] File list |
Return values
| Result | Value | Description |
|---|---|---|
| SUCCESS | 0 | Success |
Get File Size
API Prototype
long UniKey_FS_File_Get_Size(WORD* pHandle, DWORD* filesize);
Description
Get the file size.
Parameters
| Parameter | Description |
|---|---|
| *pHandle | [in] Device handle |
| *filesize | [out] The size of the file |
Return values
| Result | Value | Description |
|---|---|---|
| SUCCESS | 0 | Success |
User Reset File System Password
API Prototype
long UniKey_FS_Set_Password(WORD* pHandle, DWORD* PW1, DWORD* PW2, DWORD* PW3, DWORD* PW4);
Description
Allows a user to reset the file system password.
Parameters
| Parameter | Description |
|---|---|
| *pHandle | [in] Device handle |
| *PW1 | [in] Password 1 |
| *PW2 | [in] Password 2 |
| *PW3 | [in] Password 3 |
| *PW4 | [in] Password 4 |
Return values
| Result | Value | Description |
|---|---|---|
| SUCCESS | 0 | Success |
| ERROR_UNIKEY_GENERATE_NEW_PASSWORD | 225 | Error generating new password |
A password reset can only be successfully done after initializing the file system.
Generate RSA Key
API Prototype
long UniKey_RSA_Generate_Key(WORD* pHandle, WORD* KeyIndex);
Description
UniKey Drive has encryption and decryption modules with 1024-bit RSA keys. Calling this function can generate a 1024-bit RSA key.
Parameters
| Parameter | Description |
|---|---|
| *pHandle | [in] Device handle |
| *KeyIndex | [out] Return the handle generated key |
Return values
| Result | Value | Description |
|---|---|---|
| SUCCESS | 0 | Success |
| ERROR_UNIKEY_KEY_INDEX | 239 | The handle of the key is invalid |
Generate a DES Key
API Prototype
long UniKey_DES_Generate_Key(WORD* pHandle, DWORD* KeyIndex);
Description
Calling this function can generate a DES key.
Parameters
| Parameter | Description |
|---|---|
| *pHandle | [in] Device handle |
| *KeyIndex | [out] Return the handle generated key |
Return values
| Result | Value | Description |
|---|---|---|
| SUCCESS | 0 | Success |
| ERROR_UNIKEY_KEY_INDEX | 239 | The handle of the key is invalid |
RSA Get Number of Generated Keys
API Prototype
long UniKey_RSA_Get_Key_Counts(WORD* pHandle, DWORD* KeyIndexs);
Description
Get the number of RSA keys that are generated.
Parameters
| Parameter | Description |
|---|---|
| *pHandle | [in] Device handle |
| *KeyIndex | [out] Key count |
Return values
| Result | Value | Description |
|---|---|---|
| SUCCESS | 0 | Success |
| ERROR_UNIKEY_KEY_INDEX | 239 | The handle of the key is invalid |
DES Get Number of Generated Keys
API Prototype
long UniKey_DES_Get_Key_Counts(WORD* pHandle, DWORD* KeyIndexs);
Description
Get the number of DES keys that are generated.
Parameters
| Parameter | Description |
|---|---|
| *pHandle | [in] Device handle |
| *KeyIndex | [out] Key count |
Return values
| Result | Value | Description |
|---|---|---|
| SUCCESS | 0 | Success |
| ERROR_UNIKEY_KEY_INDEX | 239 | The handle of the key is invalid |
RSA Encryption
API Prototype
long UniKey_RSA_Encrypt(WORD* pHandle, WORD* KeyIndex, DWORD* Encrypt_Len, BYTE* Buffer);
Description
Encrypt data using RSA.
Parameters
| Parameter | Description |
|---|---|
| *pHandle | [in] Device handle |
| *KeyIndex | [in] Encrypt and decrypt using the key handle |
| *Encrypt_Len | [in] Data length to be encrypted |
| *Buffer | [in/out] Input plain text and output encrypted text |
Return values
| Result | Value | Description |
|---|---|---|
| SUCCESS | 0 | Success |
| ERROR_UNIKEY_ENCRYPT_FAILED | 228 | Could not encrypt data |
RSA Decryption
API Prototype
long UniKey_RSA_Decrypt(WORD* pHandle, WORD* KeyIndex, DWORD* Decrypt_Len, BYTE* Buffer);
Description
Decrypt data using RSA.
Parameters
| Parameter | Description |
|---|---|
| *pHandle | [in]Device handle |
| *KeyIndex | [in] Encrypt and decrypt using the key handle |
| *Decrypt_Len | [in] Length of data to be decrypted |
| *Buffer | [in/out] Input encrypted text and output plain text. |
Return values
| Result | Value | Description |
|---|---|---|
| SUCCESS | 0 | Success |
| ERROR_UNIKEY_DECRYPT_FAILED | 229 | Could not decrypt data |
| ERROR_UNIKEY_KEY_INDEX | 239 | The key handle is invalid |
DES Encryption
API Prototype
long UniKey_DES1_Encrypt(WORD* pHandle, WORD* EncryptMode, WORD* KeyIndex, DWORD* Len, BYTE* Buffer);
long UniKey_DES2_Encrypt(WORD* pHandle, WORD* EncryptMode, WORD* KeyIndex, DWORD* Len, BYTE* Buffer);
long UniKey_DES3_Encrypt(WORD* pHandle, WORD* EncryptMode, WORD* KeyIndex, DWORD* Len, BYTE* Buffer);
Description
Encrypt data using DES.
Parameters
| Parameter | Description |
|---|---|
| *pHandle | [in] Device handle |
| *EncryptMode | [in] Block cipher mode of operation |
| *KeyIndex | [in] Encrypt and decrypt using the key handle |
| *Len | [in] Length of data to be encrypted |
| *Buffer | [in/out] Input plain text and output encrypted text. |
Return values
| Result | Value | Description |
|---|---|---|
| SUCCESS | 0 | Success |
| ERROR_UNIKEY_ENCRYPT_FAILED | 228 | Could not encrypt data |
| ERROR_UNIKEY_KEY_INDEX | 239 | The key handle is invalid |
DES Decryption
API Prototype
long UniKey_DES1_Decrypt(WORD* pHandle, WORD* DecryptMode, WORD* KeyIndex, DWORD *Len, BYTE* Buffer);
long UniKey_DES2_Decrypt(WORD* pHandle, WORD* DecryptMode, WORD* KeyIndex, DWORD *Len, BYTE* Buffer);
long UniKey_DES3_Decrypt(WORD* pHandle, WORD* DecryptMode, WORD* KeyIndex, DWORD *Len, BYTE* Buffer);
Description
Encrypt data using DES.
Parameters
| Parameter | Description |
|---|---|
| *pHandle | [in] Device handle |
| *DecryptMode | [in] Block cipher mode of operation |
| *KeyIndex | [in] Encrypt and decrypt using the key handle |
| *Len | [in] Length of data to be decrypted |
| *Buffer | [in/out] Input encrypted text and output plain text. |
Return values
| Result | Value | Description |
|---|---|---|
| SUCCESS | 0 | Success |
| ERROR_UNIKEY_DECRYPT_FAILED | 229 | Could not decrypt data |
| ERROR_UNIKEY_KEY_INDEX | 239 | The key handle is invalid |
Delete RSA Key
API Prototype
long UniKey_RSA_Del_Key(WORD* pHandle, WORD* KeyIndex);
Description
Delete a RSA key.
Parameters
| Parameter | Description |
|---|---|
| *pHandle | [in] Device handle |
| *KeyIndex | [in] The handle to be deleted |
Return values
| Result | Value | Meaning |
|---|---|---|
| SUCCESS | 0 | Success |
| ERROR_UNIKEY_KEY_INDEX | 239 | The handle of the key is invalid 0 > KeyIndex > 3 |
Delete DES Key
API Prototype
long UniKey_DES_Del_Key(WORD* pHandle, WORD* KeyIndex);
Description
Delete a DES key.
Parameters
| Parameter | Description |
|---|---|
| *pHandle | [in] Device handle |
| *KeyIndex | [in] Key handle to be deleted |
Return values
| Result | Value | Description |
|---|---|---|
| SUCCESS | 0 | Success |
| ERROR_UNIKEY_KEY_INDEX | 239 | The handle of the key is invalid 0 > KeyIndex > 14 |
Get User Counts
API Prototype
long UniKey_Get_UserCount(WORD* pHandle, WORD* Count);
Description
UniKey Drive can enable 32 concurrent users to log in. This function can be called to get the number of users logged in.
Parameters
| Parameter | Description |
|---|---|
| *pHandle | [in] Device handle |
| *Count | [out] Number of users logged in |
Return values
| Result | Value | Description |
|---|---|---|
| SUCCESS | 0 | Success |
Only Allow One User to Log In
API Prototype
long UniKey_Logon_Single(WORD* pHandle, DWORD* pPassword1, DWORD* pPassword2, DWORD* pPassword3, DWORD* pPassword4);
Description
After calling this function, the UniKey Drive will only allow the active user to log in, other users will not be allowed to log in.
Parameters
| Parameter | Description |
|---|---|
| *pHandle | [in] Device handle |
| *pPassword1 | [in] Password 1 |
| *pPassword2 | [in] Password 2 |
| *pPassword3 | [in] Password 3 |
| *pPassword4 | [in] Password 4 |
Return values
| Result | Value | Description |
|---|---|---|
| SUCCESS | 0 | Success |
| ERROR_UNIKEY_INVALID_PASSWORD_OR_ID | 202 | Wrong password or UniKey HID |
Log Off the Active User
API Prototype
long UniKey_Logoff(WORD* pHandle);
Description
After calling this function, the active user will be logged out, does not affect other users’ login status.
Parameters
| Parameter | Description |
|---|---|
| *pHandle | [in] Device handle |
Return values
| Result | Value | Description |
|---|---|---|
| SUCCESS | 0 | Success |
Log Off all Users
API Prototype
long UniKey_Logoff_All(WORD* pHandle);
Description
After calling this function, all users will be logged off.
Parameters
| Parameter | Description |
|---|---|
| *pHandle | [in] Device handle |
Return values
| Result | Value | Description |
|---|---|---|
| SUCCESS | 0 | Success |
