Chapter Five -- Rockey API |
|||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
|
|
||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
Rockey application program interface (API) is the basic and most flexible encryption way of Rockey. The effect of encryption depends on usage method. We have maximal simplified the API interface. Here the examples of C/C++ interface can explain the meaning of interface parameter. Other languages are similar. Note: all interface parameters must be defined in program; it cannot transfer a NULL pointer, and otherwise cause error. short rockey 1. The function is 16-bit number, it indicates specific function word, the definition is as following:
2. handle handle
of Rockey operating handle 3. lp1, lp2 32bit
parameters 4. p1, p2, p3, p4
16bit parameters 5. buf
address of buffer In the software of final users,
the following functions's "password 3"
and "password 4" all should be 0. 1. Find rockey(RY_FIND) Objective: To check if desire
password Rockey is exist. Input
parameters: function
= RY_FIND Return value: Successful if the value returned value is 0,
otherwise it is an error code. 2. Find Next Rockey (RY_FIND_NEXT) Objective: To check if there is
any other desire password Rockey. Input
parameters: function = RY_FIND_NEXT Return value: Successful if the value returned value is 0,
otherwise it is an error code. 3. Open rockey(RY_OPEN) Objective: To open Rockey with desire password and hardware ID. Input
parameters: function = RY_OPEN Return value: Successful if the value returned value is 0,
otherwise it is an error code. 4. Close rockey(RY_CLOSE) Objective: To close respective
handle Rockey. Input
parameters: function = RY_CLOSE Return value: Successful if the value returned value is 0,
otherwise it is an error code. 5. Read rockey(RY_READ) Objective: To read contents of
user data zone. Input
parameters: function = RY_READ Return value: Successful if the value returned value is 0,
otherwise it is an error code. 6. Write rockey(RY_WRITE) Objective: To write content of
user data zone. Input
parameters: function = RY_WRITE Return value: Successful if the value returned value is 0,
otherwise it is an error code. 7. Generate Random
Number(RY_RANDOM) Objective: To get a random
number. Input
parameters: function = RY_RANDOM Return value: Successful if the value returned value is 0,
otherwise it is an error code. 8. Generate Seed
Code(RY_SEED) Objective: To get return codes
of seed code. Input
parameters: function = RY_SEED Return value: Successful if the value returned value is 0,
otherwise it is an error code. 9. Write User
ID(RY_WRITE_USERID) Objective: To write user
self-defined ID. Input
parameters: function = RY_WRITE_USERID Return value: Successful if the value returned value is 0,
otherwise it is an error code. 10. Read User
ID(RY_READ_USERID) Objective: To read user
self-defined ID. Input
parameters: function = RY_READ_USERID Return value: Successful if the value returned value is 0,
otherwise it is an error code. 11. Set Module(RY_SET_MOUDLE) Objective: To set module unit
and decrement attributes. Input
parameters: function = RY_SET_MOUDLE Return value: Successful if the value returned value is 0,
otherwise it is an error code. 12. Check
Module(RY_CHECK_MOUDLE) Objective: To check specified
module attribute. Input
parameters: function = RY_CHECK_MOUDLE Return value: Successful if the value returned value is 0,
otherwise it is an error code. 13. Write
Arithmetic(RY_WRITE_ARITHMETIC) Objective: To write
user-defined algorithm into the Rockey. Input
parameters: function = RY_WRITE_ARITHMETIC Return value: Successful if the value returned value is 0,
otherwise it is an error code. 14. Calculate 1
(RY_CALCULATE1) Objective: To allow the Rockey to do calculations according to specified
algorithm, with the result to be determined by the user algorithm. Input parameters:
function = RY_CALCULATE1 Return value: Successful if the value returned value is 0,
otherwise it is an error code. 15. Calculate 2
(RY_CALCULATE2) Objective: To allow the Rockey to do calculations according to specified
algorithm, with the result to be determined by the user algorithm. Input
parameters: function = RY_CALCULATE2 Return value: Successful if the value returned value is 0,
otherwise it is an error code. 16. Calculate 3
(RY_CALCULATE3) Objective: To allow the Rockey to do calculations according to specified
algorithm, with the result to be determined by the user algorithm. Input
parameters: function = RY_CALCULATE3 Return value: Successful if the value returned value is 0,
otherwise it is an error code. 17. Decrease Module Unit
(RY_DECREASE) Objective: To perform decreasing
operation on the specified module unit. Input
parameters: function = RY_DECREASE Return value: Successful if the value returned value is 0,
otherwise it is an error code. Error Codes
In order to help first-time
users to get started with the Rockey, several
programming examples are given here for your reference. Please note that the
examples here are intended to show only some of the functions of the Rockey and the information on how to use them. While
information on how to take good use of them is not explained here. Note: any
published experiences do not have sufficient level of security protection. Below is a simple program
written with C++. Its function is to display two
different character strings upon user's inputs. It is recommended that
programmers using other programming languages do not skip this section, since
we did not use any C language tricks here, so please be confident about what
you are reading. Note: In order to help
programmers using languages other than C to understand the following code, we
have put all the source code of sample programs and compiled executable file
under directory of ./test.
#include "conio.h" #include "stdio.h" void main() { char in;
printf("Select a string: h or g\n"); in = getch(); switch(in) { case 'h': case 'H': printf("Hello Rockey\n"); break; case 'g': case 'G': printf("Good Morning Rockey\n"); break; default: printf("Unsupport function\n"); break; } }
What we need to do next is to
add encryption code at several points for this program, so that it can only
work with our Rockey. Before writing the program,
it is necessary to plan your encryption objective first. Encryption Objective
1(Searching Rockey): The objective of this program
is to run only after the Rockey is found. If not,
it will terminate the program. This is a very simple
encryption objective, and can be completed by simply using "
Rockey Searching" function in the Rockey API. Please read the information about "Rockey Searching" under "Rockey
API Service" section above. Below is a modified program, and we put explanatory comments for any added
codes related to the encryption. For results comparison, you can run this
program both with and without the Rockey.
#include "conio.h" #include "stdio.h" #include "rockey.h" //Rockey's rockey.h file is included
void main() { char in; //***************** Below are encryption codes added ********************** WORD handle, p1, p2, p3, p4, err; //Insert variables declaration DWORD lp1, lp2; BYTE buf[1024]; p1 = 0xc p2 = 0xc err = rockey(RY_FIND, &handle, &lp1, &lp2, &p1, &p2, &p3, &p4, buf); if (err) //Any error will terminate the program { printf("Rockey not Found\n"); return; } //******************* Above are encryption codes added ******************** printf("Select a string:: h or g\n"); in = getch(); switch(in) { case 'h': case 'H': printf("Hello Rockey\n"); break; case 'g': case 'G': printf("Good Morning Rockey\n"); break; default: printf("Unsupport Function\n"); break; } }
Below are some simple
instructions on problems that you may meet during programming. First, please copy our rockey.h file into the appropriate directory. Secondly, add our obj files into the project by using "Project--Add to
project--Files...". Thirdly, none of the parameters
in the Rockey function can be a NULL pointer. Encryption Objective 2 (Seed
Code): The objective is to add several
encryption points. For better security, please access the Rockey
before calling each function. It is sufficiently feasible to
simply use the "Rockey searching" function here. However, for better understanding on how to
use Rockey API, the "Seed Code" is used
in the following program. It should be noted that you need to "Open Rockey" in the first place before using any
functions of the Rockey, and there should be a
"Close Rockey" operation corresponding to
each "Open Rockey" operation.
#include "conio.h" #include "stdio.h" #include "rockey.h" //Rockey's rockey.h file is included
void main() { char in; //***************** Below are encryption codes added ********************** WORD handle, p1, p2, p3, p4, err; //Insert variables declaration DWORD lp1, lp2; BYTE buf[1024];
p1 = 0xc p2 = 0xc err = rockey(RY_FIND, &handle, &lp1, &lp2, &p1, &p2, &p3, &p4, buf); if (err) //Any error will terminate the program { printf("Rockey not Found\n"); return; } //******************* Above are encryption codes added ******************** //*******************Open Rockey first*********************** err = rockey(RY_OPEN, &handle, &lp1, &lp2, &p1, &p2, &p3, &p4, buf); if (err) { printf("Can not open Rockey\n"); return; } //*********************Continue to run the program following the Rockey open********************** printf("Select a string:: h or g\n"); in = getch(); switch(in) { case 'h': case 'H': //*******************Passing a seed number into Rockey****************** lp2 = 0x19750316; //This is a seed, result will be sent back by the Rockey based on this seed.
err = rockey(RY_SEED, &handle, &lp1, &lp2, &p1, &p2, &p3, &p4,buf); if (err) //If there is an error, quit the program. { printf("Rockey Error\n"); break; } if (p1 == 0xe33e && p2 == 0x36dc && p3 == 0x printf("Hello Rockey\n");
break; //*****************Above is a simple application of seed code function***************** case 'g': case 'G': //*******************Passing another number into the Rockey********************* lp2 = 0xc44cc err = rockey(RY_SEED, &handle, &lp1, &lp2, &p1, &p2, &p3, &p4, buf); if (err) { printf("Rockey Error\n"); break; } if (p1 == 0x61d8 && p2 == 0x4e99 && p3 == 0xd906 && p4 == 0x4ced) printf("Good Morning Rockey\n"); break; //*************************************************************** default: printf("Unsupport Function\n"); break; } err = rockey(RY_CLOSE, &handle, &lp1, &lp2, &p1, &p2, &p3, &p4, buf); }
Encryption Objective 3
(Limited Runs): The objective is to run the
software for only three times, the user will be prompted that the software
has expired after the third run. Two methods are available to
accomplish this objective. One is to write the maximum number of runs of the
software into Rockey's user memory, and then use
READ/WRITE to limit the number of runs. The disadvantage of such doing is
that the security level would be lower, for only two basic passwords are
needed in order to read/write users' memory. Another method is to use the module
unit decreasing function of Rockey. If you do not
fully understand the "Module Unit" concept, please read chapter The module unit decreasing
function has been used in source code given below. When running this program,
please change the module unit to 3, and mark module unit 0 as
"Decreasing allowed" (Refer to chapter 8 of this instruction for Rockey application method).
#include "conio.h" #include "stdio.h" #include "rockey.h" //Rockey's rockey.h file is included
void main() { char in; //***************** Below are encryption codes added ********************** WORD handle, p1, p2, p3, p4, err; //Insert variables declaration DWORD lp1, lp2; BYTE buf[1024];
p1 = 0xc err = rockey(RY_FIND, &handle, &lp1, &lp2, &p1, &p2, &p3, &p4, buf); if (err) //Any error will terminate the program { printf("Rockey not Found\n"); return; } //******************* Above are encryption codes added ********************
//*****************Open Rockey first*********************** err = rockey(RY_OPEN, &handle, &lp1, &lp2, &p1, &p2, &p3, &p4, buf); if (err) { printf("Can not open Rockey\n"); return; } //*********************Continue to run the program following the Rockey open**********************
//***************** Test if the number of runs is zero ************** p1 = 0; //The number of runs of the software is stored in the module unit 0
err = rockey(RY_CHECK_MOUDLE, &handle, &lp1, &lp2, &p1, &p2, &p3, &p4, buf); if (err) { printf("Rockey Error\n"); return; } if (p2 != 1) //The number of runs is 0 already. { printf("Update Please\n"); return; } if (p3 == 1) //This module unit can be decreased. { p1 = 0; //Prepare for decreasing module unit 0 err = rockey(RY_DECREASE, &handle, &lp1, &lp2, &p1, &p2, &p3, &p4, buf); if (err) { printf("Rockey Error\n"); return; } } //**********************Limited Run Protection Completed*********************** printf("Select a string:: h or g\n"); in = getch(); switch (in) { case 'h': case 'H': //******************Passing a seed number into Rockey************************ lp2 = 0x19750316; //This is a seed, result will be sent back by the Rockey based on this seed. err = rockey(RY_SEED, &handle, &lp1, &lp2, &p1, &p2, &p3, &p4, buf); if (err) //If there is an error, quit the program. { printf("Rockey Error\n"); break; } if (p1 == 0xe33e && p2 == 0x36dc && p3 == 0x printf("Hello Rockey\n"); break; //*****************Above is a simple application of seed code function****************** case 'g': case 'G': //*******************Passing another number into the Rockey********************** lp2 = 0xc44cc err = rockey(RY_SEED, &handle, &lp1, &lp2, &p1, &p2, &p3, &p4, buf); if (err) { printf("Rockey Error\n"); break; } if (p1 == 0x61d8 && p2 == 0x4e99 && p3 == 0xd906 && p4 == 0x4ced) printf("Good morning Rockey\n"); break; //*************************************************************** default: printf("Unsupport function\n"); break; } err = rockey(RY_CLOSE, &handle, &lp1, &lp2, &p1, &p2, &p3, &p4, buf); }
It is very easy to remove
limited runs restriction of the above program, simply set module unit 0 to a
non-zero value and do not allow decreasing operation. Encryption Objective 4
(Multi-module encryption): The program itself has two
functions, each of which is expected to be enabled based on demands, respectively.
User can enable any one of them, as needed, while disable the other function
that is not demanded. In fact, this is a multi-module
encryption function. Same as Objective 3 above, there are two methods to
implement it. The first method is to use user's memory. The second is to use " Module Unit" provided by Rockey.
The program below will demonstrate the second method. Before running the program,
remember to set the module unit 1 and 2 to non-zero value by using
ROCKEDIT.EXE. Since this program is developed based on previous example,
please set module unit
#include "conio.h" #include "stdio.h" #include "rockey.h" //Rockey's rockey.h file is included
void main() { char in; //***************** Below are encryption codes added ********************** WORD handle, p1, p2, p3, p4, err; //Insert variables declaration DWORD lp1, lp2; BYTE buf[1024];
p1 = 0xc err = rockey(RY_FIND, &handle, &lp1, &lp2, &p1, &p2, &p3, &p4, buf); if (err) //Any error will terminate the program { printf("Rockey not Found\n"); return; } //******************* Above are encryption codes added ********************
//*****************Open Rockey first************************ err = rockey(RY_OPEN, &handle, &lp1, &lp2, &p1, &p2, &p3, &p4, buf); if (err) { printf("Can not Open Rockey\n"); return; }
//***************** Test if the number of runs is zero ************** p1 = 0; //The number of runs of the software is stored in the module unit 0 err = rockey(RY_CHECK_MOUDLE, &handle, &lp1, &lp2, &p1, &p2, &p3, &p4, buf); if (err) { printf("Rockey Error\n"); err = rockey(RY_CLOSE, &handle, &lp1, &lp2, &p1, &p2, &p3, &p4, buf); return; } if (p2 != 1) //The number of runs is 0 already. { printf("Update Please\n"); err = rockey(RY_CLOSE, &handle, &lp1, &lp2, &p1, &p2, &p3, &p4, buf); return; } if (p3 == 1) //This module unit can be decreased. { p1 = 0; //Prepare for decreasing module unit 0 err = rockey(RY_DECREASE, &handle, &lp1, &lp2, &p1, &p2, &p3, &p4, buf); if (err) { printf("Rockey Error\n"); err = rockey(RY_CLOSE, &handle, &lp1, &lp2, &p1, &p2, &p3, &p4, buf); return; } } //*********************Limited Run Protection Completed*********************** printf("Select a string: h or g\n"); in = getch(); switch (in) { case 'h': case 'H': //*****************Test if the selected function can work.************** p1 = 1; //H function is controlled by module unit 1 err = rockey(RY_CHECK_MOUDLE, &handle, &lp1, &lp2, &p1, &p2, &p3, &p4, buf); if (err) { printf("Rockey Error\n"); rockey(RY_CLOSE, &handle, &lp1, &lp2, &p1, &p2, &p3, &p4, buf); return; } if (p2 != 1) //This module unit is 0, don't execute the function, terminate it immediately. { printf("Function Invalid\n"); rockey(RY_CLOSE, &handle, &lp1, &lp2, &p1, &p2, &p3, &p4, buf); return; } //*******************Hmodule encryption completed.*************************
//******************Passing a seed number into Rockey************************* lp2 = 0x19750316; //This is a seed, result will be sent back by the Rockey based on this seed. err = rockey(RY_SEED, &handle, &lp1, &lp2, &p1, &p2, &p3, &p4, buf); if (err) //If there is an error, quit the program. { printf("Rockey Error\n"); break; } if (p1 == 0xe33e && p2 == 0x36dc && p3 == 0x printf("Hello Rockey\n"); break; //****************Above is a simple application of seed code function******************* case 'g': case 'G': //***************Test if the selected function can work.****************** p1 = 2; //G function is controlled by module unit 2 err = rockey(RY_CHECK_MOUDLE, &handle, &lp1, &lp2, &p1, &p2, &p3, &p4, buf); if (err) { printf("Rockey Error\n"); rockey(RY_CLOSE, &handle, &lp1, &lp2, &p1, &p2, &p3, &p4, buf); return; } if (p2 != 1) //This module unit is 0, don't execute the function, terminate it immediately. { printf("Function Invalid\n"); rockey(RY_CLOSE, &handle, &lp1, &lp2, &p1, &p2, &p3, &p4, buf); return; } //**********************Gmodule encryption completed.**********************
//*********************Passing another number into the Rockey******************** lp2 = 0xc44cc err = rockey(RY_SEED, &handle, &lp1, &lp2, &p1, &p2, &p3, &p4, buf); if (err) { printf("Rockey Error\n"); break; } if (p1 == 0x61d8 && p2 == 0x4e99 && p3 == 0xd906 && p4 == 0x4ced) printf("Good Morning Rockey\n"); break; //*************************************************************** default: printf("Unsupport Function\n"); break; } err = rockey(RY_CLOSE, &handle, &lp1, &lp2, &p1, &p2, &p3, &p4, buf); }
Encryption Objective 5 (Same
password Cascading): After the user selects one of
the software functions, to add one more function, he/she needs to perform
certain processing to user's Rockey according to
the method given by the "Encryption Objective 4". Is it possible to
give the user a new Rockey with the same password
instead of conducting processing to the user's existing Rockey?
This new Rockey can be used to enable another
function of the software, therefore the user can install the Rockey corresponding to the function he/she needs to use,
and can combine the two Rockeys together when
needed so as to use the two functions simultaneously, wouldn't that be more
convenient and easier? The unique same password
cascading feature of Rockey can just meet the above
requirement. Of course, you need to apply some programming tricks here to
accomplish the purpose, please refer to the program below. The change to the
definition of the handle is important and easy to be overlooked, please pay
attention to it.
#include "conio.h" #include "stdio.h" #include "rockey.h" //Rockey's rockey.h file is included
int i; //Add one global variable for recording the count of same number Rockeys. WORD handle[16]; //To simplify, we use the global variable to store the data needed for Rockey. WORD p1, p2, p3, p4, err; DWORD lp1, lp2; BYTE buf[1024];
void CloseAll() //This function is used to close all same-number Rockeys that have been cascaded. { int j; for (j = 0; j < i; j++) { err = rockey(RY_CLOSE, &handle[j], &lp1, &lp2, &p1, &p2, &p3, &p4, buf); } }
void main() { char in; //***************** Below are encryption codes added ********************** int j;
p1 = 0xc err = rockey(RY_FIND, &handle[0], &lp1, &lp2, &p1, &p2, &p3, &p4, buf); if (err) //Any error will terminate the program { printf("Rockey not Found\n"); return; } //******************* Above are encryption codes added ********************
//*******************Open Rockey first********************** err = rockey(RY_OPEN, &handle[0], &lp1, &lp2, &p1, &p2, &p3, &p4, buf); if (err) { printf("Can not open Rockey\n"); return; } //*********************Continue to run the program following the Rockey open********************** i = 1; //One Rockey has been found while (err == 0) //Start to enumerate all same number Rockey. { err = rockey(RY_FIND_NEXT, &handle[i], &lp1, &lp2, &p1, &p2, &p3, &p4, buf); if (err == ERR_NOMORE) break; //If no more same number Rockey is available, end the loop. if (err) { CloseAll(); //If there is an error, close all opened Rockey and quit the program. return; }
err = rockey(RY_OPEN, &handle[i],&lp1,&lp2,&p1, &p2, &p3, &p4, buf); if (err) { CloseAll(); //If there is an error, close all opened Rockey and quit the program. return; } i++; //Record number of opened Rockeys }
//To save space, limited runs function is skipped here. printf("Select a string:: h or g\n"); in = getch(); switch(in) { case 'h': case 'H': //*****************Test if the selected function can work.**************** for (j = 0; j < i; j++) //Test all available Rockey for validate Module Unit { p1 = 1; err = rockey(RY_CHECK_MOUDLE, &handle[j], &lp1, &lp2, &p1, &p2, &p3, &p4, buf); if (err) { printf("Rockey Error\n"); CloseAll(); return; } if (p2 != 1) //The module unit 1 of this Rockey is zero, test next. continue; else //The module unit 1 of this Rockey has been opened. break; } if (j == i) //All Rockey did not open module 1 { printf("Function Invalid\n"); break; } //**********************Hmodule encryption completed.*********************
//*********************Passing a seed number into Rockey**************** lp2 = 0x19750316; //This is a seed, result will be sent back by the Rockey based on this seed. err = rockey(RY_SEED, &handle[j],&lp1,&lp2,&p1, &p2, &p3, &p4, buf); if (err) //If there is an error, quit the program. { printf("Rockey Error\n"); break; } if (p1 == 0xe33e && p2 == 0x36dc && p3 == 0x printf("Hello Rockey\n"); break; //*********************Above is a simple application of seed code function************* case 'g': case 'G': //*********************Test if the selected function can work*********** for (j = 0; j < i; j++) //Test all available Rockey for validate Module Unit { p1 = 2; err = rockey(RY_CHECK_MOUDLE, &handle[j], &lp1, &lp2, &p1, &p2, &p3, &p4, buf); if (err) { printf("Rockey Error\n"); CloseAll(); return; } if (p2 != 1) //The module unit 2 of this Rockey is zero, test next. continue; else //The module unit 2 of this Rockey has been opened. break; } if (j == i) //All Rockey did not open module 2 { printf("Function Invalid\n"); break; } //***************Gmodule encryption completed.*****************************
//*********************Passing another number into the Rockey******************** lp2 = 0xc44cc err = rockey(RY_SEED, &handle[j],&lp1,&lp2, &p1, &p2, &p3, &p4, buf); if (err) { printf("Rockey Error\n"); break; } if (p1 == 0x61d8 && p2 == 0x4e99 && p3 == 0xd906 && p4 == 0x4ced) printf("Good Morning Rockey\n"); break; //*************************************************************** default: printf("Unsupport Function\n"); break; } CloseAll(); return; } |
|||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
|
|||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
Copyright
1997-2006 FEITIAN Technology Co.,Ltd.
All rights reserved. |