Chapter Nine -- NetRockey4ND Developer's Guide |
||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
|
|
|||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
NetRockey4ND is a network aware software protection system designed to limit the number of simultaneous users who can access a software application. It combines all the functionality of the standard Rockey4ND system, with the ability to work seamlessly in LAN/WAN environments that support the UDP/TCP, IPX or NetBIOS protocols. NetRockey4ND was engineered to support stand alone or redundant server environments on both the Windows and Linux platforms. The system includes powerful and intuitive network monitoring and testing tools that ease the implementation effort. 1. NetRockey4ND Developer’s Kit The developing tools for NetRockey4ND under the directory “net”: <Client> DLLs and configuration files for the NetRockey4ND client and test program. 2.The use of theNetRockey4ND tools. 2.1)Installing the NetRockey4ND SDK Step 1. Open the terminal of the system: Step 2. Run the script name for inst under the directory "ROCKEY4ND/net" to install the SDK: 2.2)Uninstalling the NetRockey4ND SDK Run the script name for uninst under the directory "ROCKEY4ND/net" to uninstall the SDK: 2.3)Testing the NetRockey4ND Step 1. Compile test application in the directory “ROCKEY4ND/net/client/test": Step 2. Run test application: Step 3. If you press Enter, it will continue: Step 4. If you press q, it will end test: 2.4)Logging file Step 1. Find the file named syslog(/etc/rc.d/init.d/syslog start OR /etc/init.d/syslog start):
Step 2. Check log file: 2.5)Client Configure file Step 1. Open the file for configuring Client under the directory " /etc/rynet": Step 2. If it cann't be writed, you should change the attribute: Step 3. After changing the attribute,You enter the file for configuring client again. Now you can write the parameters of client configuration: Finally save and quit! 2.6)Server Configure file You can configure server in accordance to the above examples: Finally save and quit! After configuration is successful, you can first run "/etc/init.d/ryserv stop" to stop server, and then run "/etc/init.d/ryserv start" to start server. 2.7)Monitor the NetRockey4ND Run rockey4nd-monitor under the directory "ROCKEY4ND/net/monitor" :
3. NetRockey4ND Basic Concepts 3.1)Configuration Files There is a configuration file for the Service program (SvrCfg.ini), and one for the Client program (CliCfg.ini). The service and client programs take their network settings from the configuration files. The developer may use a text editor or tools provided by Feitian to edit such configuration file parameters as: protocol type, time-to-live, server address and other information required for the dongle to attach to the network. 3.2)Log Files The NetRockey4ND log file (svrlog.txt) records the running status of the service program. It can be helpful if you encounter a problem with the service program. The path and name of the log file may be configured in the SvrCfg.ini file. 3.3)Port and Group Information The UDP/TCP and IPX protocols require the specification of a port number. Port numbers range from 0 to 65535. The default port number for NetRockey4ND is 3152. 3152 is registered with IASA and should be available on most networks. If it is occupied though, the NetRockey4ND service program will report a “bind” error. If a bind error occurs you may want to move NetRockey4ND to an available port; the port number can be changed in the SvrCfg.ini and CliCfg.ini file. The NetBIOS protocol does not use a port number. It uses a group name. The group name is a character string that may be a maximum of 14 characters in length. Each server in a NetBIOS network has both a computer name and a group name. The group name for the service program may be altered in the SvrCfg.ini file and the CliCfg.ini file. All clients and servers that need to communicate in a NetBIOS network need to have the same group name. 3.4) Network Address Each computer in network has a unique address. A UDP/TCP network (IPv4) uses IP addresses that may look like: 192.168.0.1. An IPX network uses a MAC address that may look like: 00-35-4f-20-00-32. A NetBIOS network uses both a computer name and a group name. 3.5)Search Mode The NetRockey4ND client program will search for the address of the service 3.6)Open Mode The NetRockey4ND client programs issue an “open” command to the service program. This open command is equivalent to a network login and it is the means by which the service program limits the number of users that can attach to the application. There are two operating modes for the open command: private and share. The default setting is private mode. In private mode operation the service program adds “1” each time a user attaches to the application. If the calculated quantity reaches the maximum set by the developer, the open command will fail, the service program will issue an error message and the user will not be allowed to access the application. In share mode, all programs in the same computer share one user number. No matter how many times the computer accesses the service program, it is considered to be one user. Share mode is appropriate if the number of computers, rather than the number of users that attach to an application, need to be limited. The open mode is set with the lp2 parameter in the open operation (See Chapter Five -- Rockey4ND API for an explanation of the open operation.) The low byte of the lp2 parameter sets the NetRockey4ND module number that will store the maximum number of simultaneous users (see item 3.8 below), and the high byte sets the open mode, and the low byte sets the login module. 3.7)Time Out Each time the client sends data to the server it will wait a time period defined by the “time out” parameter. If the client does not receive a response after the time out period, it will quit and return an error code. The unit of time for the time out parameter is seconds and the default is two. In automatic search mode, the time out is also the period that the client program will wait for a response to its broadcast message. The time out parameter can be changed in the CliCfg.ini file. 3.8)Maximum Number of Simultaneous Users The maximum number of simultaneous users that will be allowed to access an application will be set by a value stored in a NetRockey4ND module. For example, if you write “5” to module number 0, module 0 can be used to set a limit of five users who can simultaneously use your application. A NetRockey4ND dongle has 64 modules, so as many as 64 user groups can have individualized application access limits. The NetRockey4ND Editor program can be used to write a value to a module, but it is impossible to read the value. 3.9)Client Time to Live (TTL) This parameter is set in the service program (SvrCfg.ini). The time unit is minutes 3.10)Open Module A module can only be opened once in a single process with security in mind. You may set the handle as a global variable to use it in every thread. 4. NetRockey4ND API 4.1)NetRockey4ND function NetRockey4ND supports function call, the 4 functions are below: DWORD WINAPI NetRockey NetRockey is the main function for NetRockey4ND. 4.2)Parameters 4.2.1)NetRockey4ND provides Net Rockey4ND function call. A return code of “0” indicates the operation succeeded, all other return codes indicate an error, refer to section 6 Return Code. Function is a 16-bit number, it indicates the specific function of NetRockey4ND, and it is defined below:
Note: [*]:Function Parameters 9, 11 and 13 are not valid for NetRockey4ND because they require the Advanced passwords. The Service program will not recognize these parameters. The Editor for the standard (stand alone)Rockey4ND may be used to update these functions in the NetRockey4ND product. So these NetRockey4ND functions only require basic passwords. lp1,lp2 long parameter (32 bit) Please refer to the API section for more detail. 4.2.2)SetIniPathName Set the pathname of a client configuration file. A return code of “0” indicates the operation succeeded, all other return codes indicate an error. IniName is the name of file. 4.2.3)NrGetLastError Get the last error code from NetRockey4ND. This function will also return the error code description. Please refer to section 6 Return Code to see a list of error codes. 4.2.4)NrGetVersion Get the version number of D11. The high WORD of return value is main version number, and the low WORD is secondary version number. 5. API The NetRockey4ND API function parameters are defined in detail below. The password 3 and password 4 should be set 0 in the final products you offer to your end users. The functions marked with [*] require advanced password 3 and password 4. 5.1) Find a NetRockey4ND dongle (RY_FIND) Objective: Find NetRockey4ND according to parameters set in the Client configuration file. Input parameters: function = RY_FIND 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 NetRockey4ND Hardware ID (HID) to *lp1 and the server name to the buffer. 5.2)Find the Next NetRockey4ND dongle (RY_FIND_NEXT) Objective: To check if another NetRockey4ND dongle is attached to the network. Input parameters: function = 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 NetRockey4ND Hardware ID (HID) to *lp1 and the server name to the buffer. 5.3) Open the NetRockey4ND dongle (RY_OPEN) Objective: To log into a specified NetRockey4ND module and get a handle number to enable other operations. Input parameters: function = RY_OPEN For example, *lp2=1 means log in module 1 in private mode. *lp2 = 0x11 means log in module 1 in share mode. Return value: A return value = “0” indicates that the function worked correctly. Any other return value indicates an error. Note: You must use the same *p1, *p2 values with the RY_FIND and RY_FIND_NEXT functions. A successful operation will return the correct NetRockey4ND handle. “buffer” will return the NetRockey4ND seed result. (if it is designed. ) 5.4) Close the NetRockey4ND dongle (RY_CLOSE) Objective: To close a NetRockey4ND service. Input parameters: function = RY_CLOSE Return value: A return value = “0” indicates that the function worked correctly. Any other return value indicates an error. 5.5) Read from a NetRockey4ND dongle (RY_READ) Objective: To read the contents of the User Data Zone (UDZ). Input parameters: function = RY_READ 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. 5.6) Write to a NetRockey4ND dongle (RY_WRITE) Objective: To write data to the User Data Zone. (UDZ) Input parameters: function = RY_WRITE Return value: A return value = “0” indicates that the function worked correctly. Any other return value indicates an error. 5.7) Generate a Random Number (RY_RANDOM) Objective: To get a random number. Input parameters: function = RY_RANDOM 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 address populated with the random number. 5.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 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: 5.9) Write the User ID (RY_WRITE_USERID) Note: This function is not supported by NetRockey4ND. This function may be achieved in the Editor of stand alone Rockey4ND before the NetRockey4ND is released. 5.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 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 data stored in the UIZ.
Note: This function is not supported by NetRockey4ND. This function may be achieved in the Editor of stand alone Rockey4ND before the NetRockey4ND is released. 5.12) Check a NetRockey4ND Module (RY_CHECK_MODULE) Objective: To read the attributes of a specific NetRockey4ND module. Input parameters: function = RY_CHECK_MODULE 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 is not zero), and “*p3” populated with the value from the Decrement attribute (1 = module can be decreased). 5.13) Write Arithmetic (RY_WRITE_ARITHMETIC) Note: This function is not supported by NetRockey4ND. This function may be achieved in the Editor of stand alone Rockey4ND before the NetRockey4ND is released. 5.14) Calculate 1 (RY_CALCULATE1) Objective: To return the results of calculation 1 performed in NetRockey4ND. Input parameters: function = RY_CALCULATE1 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 the results of the instruction: 5.15) Calculate 2 (RY_CALCULATE2) Objective: To return the results of calculation 2 performed in NetRockey4ND. Input parameters: function = RY_CALCULATE2 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 instruction. 5.16) Calculate 3 (RY_CALCULATE3) Objective: To return results of calculation 3 performed in NetRockey4ND. Input parameters: function = RY_CALCULATE3 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 instruction. 5.17) Decrease Module Unit (RY_DECREASE) Objective: To decrease the value in a specified NetRockey4ND module by “1”. Input parameters: function = RY_DECREASE 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”. 6. Return Codes 6.1)NetRockey4ND Return Codes There are two kinds of return codes: Normal and Extended. Normal return codes are the return values of the NetRockey4ND API. Extended error codes are values returned from the NrGetLastError function. Extended error codes are related to network issues. Normal return codes:
Below are network error codes, NrGetLastError function can return extended error codes.
6.2)NetRockey4ND Extended Return Codes Run the NrGetLastError function after receiving any network related return code. The result will be an error code constant that you can use to look up more detailed error information in the TCP/UDP or IPX specifications.
6.3)NetBios Extended Return Codes Extended return codes for NetBIOS networks:
|
||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
|
||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
Copyright (C) 2007-2009 Feitian Technologies Co.,Ltd.
All rights reserved. |