Chapter Five -- Rockey4ND API
The Rockey4ND Application Programming Interface (API) is the most flexible and powerful means of protecting your software. The security level of your software is determined by how you implement the API. The API set has been simplified and is intended to make the Rockey4ND programming effort as effective as possible. API encryption enables you to call Rockey4ND in your application to enhance its security level. You may check the existence of the dongle anywhere in your application and take actions as a result of the check. You may also check the data you stored in the UDZ. You may use the Editor program to set and write data to the modules, write algorithms to the User Algorithm Zone (UAZ), user information to the User ID zone (UID) or take other actions. All such operations may be performed with the API. 1.Rockey4ND Function Prototype and Definition WORD Rockey ( WORD function, WORD* handle, DWORD* lp1, DWORD* lp2, WORD* p1, WORD* p2, WORD* p3, WORD* p4, BYTE* buffer ); FEITIAN provides developers with a unified function from which they can employ all Rockey4ND operations. This function is defined as a multi-function function. Below is a call example for C language, and we will discuss future applications in a similar way. retcode = Rockey(function,handle,lp1,lp2,p1,p2,p3,p4,buffer); The “Rockey4ND” function parameters are defined as:
Parameter Name | Parameter Type | Parameter Meaning
Function | A 16-bit number | API function
Handle | Address of a 16-bit number | Rockey4ND session address
lp1 | Address of a 32-bit number | long parameter 1
lp2 | Address of a 32-bit number | long parameter 2
p1 | Address of a 16-bit number | parameter 1
p2 | Address of a 16-bit number | parameter 2
p3 | Address of a 16-bit number | parameter 3
p4 | Address of a 16-bit number | parameter 4
Buffer | Address of a 8-bit number | Buffer
Note: All interface parameters must be defined in your program. Rockey4ND cannot transfer NULL or 0 pointers. Use of Null or 0 pointers in your program will generate an error. a)“function” is a 16-bit number. It stands for the specific function and it is defined below:
RY_FIND | 1 | // Find Rockey4ND
RY_FIND_NEXT | 2 | // Find next Rockey4ND
RY_OPEN | 3 | // Open Rockey4ND
RY_CLOSE | 4 | // Close Rockey4ND
RY_READ | 5 | // Read Rockey4ND
RY_WRITE | 6 | // Write Rockey4ND
RY_RANDOM | 7 | // Generate Random Number
RY_SEED | 8 | // Generate Seed Code
RY_WRITE_USERID | 9 | // Write User ID
RY_READ_USERID | 10 | // Read User ID
RY_SET_MOUDLE | 11 | // Set Module
RY_CHECK_MOUDLE | 12 | // Check Module
RY_WRITE_ARITHMETIC | 13 | // Write Arithmetic
RY_CALCULATE1 | 14 | // Calculate 1
RY_CALCULATE2 | 15 | // Calculate 2
RY_CALCULATE3 | 16 | // Calculate 3
RY_DECREASE | 17 | // Decrease Module Unit
b ) “handle” is the pointer for Rockey4ND operation’s handle. c )“lp1” and “lp2” are the pointers for long integer parameters. Their content depends on the functions. d ) “p1”, “p2”, “p3” and “p4” are the pointers for short integer parameters. Their content depends on the functions. e ) “buffer” is the pointer for character buffer. Its content depends on the functions. 2.Rockey4ND API Services Here we discuss the API services in detail. The following functions marked with [*] require the two Advanced passwords. Note: p3 and p4 are Advanced passwords. They are for developers to operate on the dongle. The Advanced passwords should not appear in the software you offer to your customers and you should set the two Advanced passwords “0” when searching for dongles in your application. 2.1) Find a Rockey4ND dongle (RY_FIND) Objective: To check if a specific Rockey4ND is attached to the USB port. Input parameters: function = RY_FIND *p1 = Password 1 *p2 = Password 2 *p3 = Password 3 (optional) *p4 = Password 4 (optional) Return value: A return value = “0” indicates that the function worked correctly. Any other return value indicates an error. A successful operation will write the Rockey4ND Hardware ID (HID) to *lp1. 2.2) Find the Next Rockey4ND dongle (RY_FIND_NEXT) Objective: To check if another specific Rockey4ND is attached to the USB port. Input parameters: function = RY_FIND_NEXT *p1 = Password 1 *p2 = Password 2 *p3 = Password 3 (optional) *p4 = Password 4 (optional) *lp1 = The hardware ID of the last dongle found by RY_FIND or RY_FIND_NEXT Return value: A return value = “0” indicates that the function worked correctly. Any other return value indicates an error. A successful operation will write the Rockey4ND Hardware ID (HID) to *lp1. 2.3) Open the Rockey4ND dongle (RY_OPEN) Objective: To open a Rockey4ND dongle with specified passwords or hardware ID. Input parameters: function = RY_OPEN *p1 = Password 1 *p2 = Password 2 *p3 = Password 3 (optional) *p4 = Password 4 (optional) *lp1= Hardware ID Return value: A return value = “0” indicates that the function worked correctly. Any other return value indicates an error. A successful operation will write the handle address to the *handle parameter 2.4) Close the Rockey4ND dongle (RY_CLOSE) Objective: To close a Rockey4ND dongle with a specific handle. Input parameters: function = RY_CLOSE *handle = Rockey4ND's handle Return value: A return value = “0” indicates that the function worked correctly. Any other return value indicates an error. 2.5) Read the Rockey4ND dongle (RY_READ) Objective: To read the contents of the User Data Zone (UDZ). Input parameters: function = RY_READ *handle = Rockey4ND's handle *p1 = off set of UDZ(must be even) *p2 = length (unit is byte, must be even) buf = address of buffer Return value: A return value = “0” indicates that the function worked correctly. Any other return value indicates an error. A successful operation will result in the contents of the UDZ written to the memory buffer. 2.6) Write to the Rockey4ND dongle (RY_WRITE) Objective: To write data to the User Data Zone. (UDZ) Input parameters: function = RY_WRITE *handle = Rockey4ND's handle *p1 = off set of UDZ( must be even) *p2 = length (unit is byte, must be even) buf = address of buffer Return value: A return value = “0” indicates that the function worked correctly. Any other return value indicates an error. 2.7) Generate a Random Number (RY_RANDOM) Objective: To get a random number from the dongle. Input parameters: function = RY_RANDOM *handle = Rockey4ND's handle Return value: A return value = “0” indicates that the function worked correctly. Any other return value indicates an error. A successful operation will result in the *p1,*p2,*p3,*p4 address populated with the random number. 2.8) Generate Seed Code Return Values (RY_SEED) Objective: To get return codes from the input of a seed code. Input parameters: function = RY_SEED *handle = Rockey4ND's handle *lp2 = Seed Code Return value: A return value = “0” indicates that the function worked correctly. Any other return value indicates an error. A successful operation will result in the following addresses populated with seed code return values: *p1 = Return Code 1 *p2 = Return Code 2 *p3 = Return Code 3 *p4 = Return Code 4 2.9) Write the User ID [*] (RY_WRITE_USERID) Objective: To write the user defined “User ID” to the User ID Zone (UIZ). Input parameters: function = RY_WRITE_USERID *handle = Rockey4ND's handle *lp1 = User ID Return value: A return value = “0” indicates that the function worked correctly. Any other return value indicates an error. 2.10) Read User ID (RY_READ_USERID) Objective: To read the user defined “User ID” from the User ID Zone (UIZ). Input parameters: function = RY_READ_USERID *handle = Rockey4ND's handle Return value: A return value = “0” indicates that the function worked correctly. Any other return value indicates an error. A successful operation will result in the *lp1 address populated with the User ID. 2.11) Set a Rockey4ND Module [*] (RY_SET_MOUDLE) Objective: To write a value to a specific Rockey4ND module and set the Decrement attribute. Input parameters: function = RY_SET_MOUDLE *handle = Rockey4ND's handle *p1 = Module Number *p2 =Module Unit Value *p3 = If decreasing is allowed (1 = allowed, 0 = not allowed) Return value: A return value = “0” indicates that the function worked correctly. Any other return value indicates an error. A successful operation will result in module unit # “*p1” storing value “*p2” and the Decrement attribute set to “0” or “1”. 2.12) Check a Rockey4ND Module (RY_CHECK_MOUDLE) Objective: To read the attributes of a specific Rockey4ND module. Input parameters: function = RY_CHECK_MOUDLE *handle = Rockey4ND's handle *p1 = Module Number Return value: A return value = “0” indicates that the function worked correctly. Any other return value indicates an error. A successful operation will result in “*p2” populated in the value from the Zero Value attribute (1 = module value is not zero), and “*p3” populated with the value from the Decrement attribute (1 = module can be decreased). 2.13) Write Arithmetic [*] (RY_WRITE_ARITHMETIC) Objective: To write user-defined mathematical instructions to the User Algorithm Zone (UAZ). Input parameters: function = RY_WRITE_ARITHMETIC *handle = Rockey4ND's handle *p1 = position of first instruction in UAZ buffer = buffer address of the algorithm command string Return value: A return value = “0” indicates that the function worked correctly. Any other return value indicates an error. A successful operation will result in the UAZ populated with the algorithm command string from the buffer. 2.14)Calculate 1 (RY_CALCULATE1) Objective: To return the results of a calculation performed in Rockey4ND, using input provided by the developer and the RY_CALCULATE1 function. Input parameters: function = RY_CALCULATE1 *handle = Rockey4ND's handle *lp1 = Start point of calculation *lp2 = Module number *p1 = Input value 1 *p2 = Input value 2 *p3 = Input value 3 *p4 = Input value 4 Return value: A return value = “0” indicates that the function worked correctly. Any other return value indicates an error. A successful operation will result in the addresses p1, p2, p3 and p4 populated with the results of the calculation. 2.15) Calculate 2 (RY_CALCULATE2) Objective: To return the results of a calculation performed in Rockey4ND, using input provided by the developer and the RY_CALCULATE2 function. Input parameters: function = RY_CALCULATE2 *handle = Rockey4ND's handle *lp1 = Start point of calculation *lp2 = Seed Code (32-bit) *p1 = Input value 1 *p2 = Input value 2 *p3 = Input value 3 *p4 = Input value 4 Return value: A return value = “0” indicates that the function worked correctly. Any other return value indicates an error. A successful operation will result in the addresses p1, p2, p3 and p4 populated with the results of the calculation. 2.16) Calculate 3 (RY_CALCULATE3) Objective: To return results of a calculation performed in Rockey4ND, using input provided by the developer and the RY_CALCULATE3 function. Input parameters: function = RY_CALCULATE3 *handle = Rockey4ND's handle *lp1 = Start point of calculation *lp2 = Module number *p1 = Input value 1 *p2 = Input value 2 *p3 = Input value 3 *p4 = Input value 4 Return value: A return value = “0” indicates that the function worked correctly. Any other return value indicates an error. A successful operation will result in the addresses p1, p2, p3 and p4 populated with the results of the calculation. 2.17)Decrease Module Unit (RY_DECREASE) Objective: To decrease the value in a specified Rockey4ND module by “1”. Input parameters: function = RY_DECREASE *handle = Rockey4ND's handle *p1 = Module number Return value: A return value = “0” indicates that the function worked correctly. Any other return value indicates an error. A successful operation will reduce the value stored in module *p1 by “1”. 3.Return Codes
RETURN CODE | Value | DESCRIPTION
ERR_SUCCESS | 0 | Success
ERR_NO_ROCKEY | 3 | No Rockey4ND dongle
ERR_INVALID_PASSWORD | 4 | Found Rockey4ND dongle, but Basic passwords are incorrect
ERR_INVALID_PASSWORD_OR_ID | 5 | Wrong password or Rockey4ND HID
ERR_SETID | 6 | Set Rockey4ND HID wrong
ERR_INVALID_ADDR_OR_SIZE | 7 | Read/Write address or length is wrong
ERR_UNKNOWN_COMMAND | 8 | No such command
ERR_NOTBELEVEL3 | 9 | Internal error
ERR_READ | 10 | Read error
ERR_WRITE | 11 | Write error
ERR_RANDOM | 12 | Random number error
ERR_SEED | 13 | Seed code error
ERR_CALCULATE | 14 | Calculate error
ERR_NO_OPEN | 15 | No open dongle before operating dongle
ERR_OPEN_OVERFLOW | 16 | Too many open dongles (>16)
ERR_NOMORE | 17 | No more dongle
ERR_NEED_FIND | 18 | No Find before FindNext
ERR_DECREASE | 19 | Decrease error
ERR_AR_BADCOMMAND | 20 | Arithmetic instruction error
ERR_AR_UNKNOWN_OPCODE | 21 | Arithmetic operator error
ERR_AR_WRONGBEGIN | 22 | Const number can't be used on first arithmetic instruction
ERR_AR_WRONG_END | 23 | Const number can't be used on last arithmetic instruction
ERR_AR_VALUEOVERFLOW | 24 | Const number > 63
ERR_TOOMUCHTHREAD | 25 | Too many (>100) threads in the single process open the dongle
ERR_RECEIVE_NULL | 0x100 | Receive null
ERR_UNKNOWN_SYSTEM | 0x102 | Unknown operating system
ERR_UNKNOWN | 0xffff | Unknown error
Copyright (C) 2007-2009 Feitian Technologies Co.,Ltd. All rights reserved. Last Updated: Agu 5, 2009