ROCKEY6 SMART User Manual V1.

3


i






ROCKEY6 SMART User Guide

Version 1.3















Copyright 2002-2007 Feitian Technologies Co., Ltd.
http://www.FTsafe.com
ROCKEY6 SMART User Manual V1.3


ii

Feitian Technologies Co., Ltd.
Software Developers Agreement
All Products of Feitian Technologies Co., Ltd. (Feitian) including, but not limited to, evaluation
copies, diskettes, CD-ROMs, hardware and documentation, and all future orders, are subject to the
terms of this Agreement. If you do not agree with the terms herein, please return the evaluation
package to us, postage and insurance prepaid, within seven days of their receipt, and we will reimburse
you the cost of the Product, less freight and reasonable handling charges.
1. Allowable Use You may merge and link the Software with other programs for the sole purpose
of protecting those programs in accordance with the usage described in the Developers Guide. You
may make archival copies of the Software.
2. Prohibited Use The Software or hardware or any other part of the Product may not be copied,
reengineered, disassembled, decompiled, revised, enhanced or otherwise modified, except as
specifically allowed in item 1. You may not reverse engineer the Software or any part of the product or
attempt to discover the Softwares source code. You may not use the magnetic or optical media
included with the Product for the purposes of transferring or storing data that was not either an original
part of the Product, or a Feitian provided enhancement or upgrade to the Product.
3. Warranty Feitian warrants that the hardware and Software storage media are substantially
free from significant defects of workmanship or materials for a time period of twelve (12) months from
the date of delivery of the Product to you.
4. Breach of Warranty In the event of breach of this warranty, Feitians sole obligation is to
replace or repair, at the discretion of Feitian, any Product free of charge. Any replaced Product
becomes the property of Feitian. Warranty claims must be made in writing to Feitian during the
warranty period and within fourteen (14) days after the observation of the defect. All warranty claims
must be accompanied by evidence of the defect that is deemed satisfactory by Feitian. Any Products
that you return to Feitian, or a Feitian authorized distributor, must be sent with freight and insurance
ROCKEY6 SMART User Manual V1.3


iii
prepaid.
EXCEPT AS STATED ABOVE, THERE IS NO OTHER WARRANTY OR REPRESENTATION OF THE
PRODUCT, EXPRESSED OR IMPLIED, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED
WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE.
5. Limitation of Feitians Liability Feitians entire liability to you or any other party for any cause
whatsoever, whether in contract or in tort, including negligence, shall not exceed the price you paid for
the unit of the Product that caused the damages or are the subject of, or indirectly related to the cause
of action. In no event shall Feitian be liable for any damages caused by your failure to meet your
obligations, nor for any loss of data, profit or savings, or any other consequential and incidental
damages, even if Feitian has been advised of the possibility of damages, or for any claim by you based
on any third-party claim.
6. Termination This Agreement shall terminate if you fail to comply with the terms herein. Items
2, 3, 4 and 5 shall survive any termination of this Agreement.












ROCKEY6 SMART User Manual V1.3


iv

PREFACE
ROCKEY6 SMART dongle is a newly developed powerful security product from FEITIAN
Technologies. It is a smart card kernel based USB device that combines software protection dongle and
smart card technologies in a very small form factor. It supports multiple applications including software
protection, personal identification and authentication, data security and protected electronic
transactions. This manual will guide you on how to use ROCKEY6 SMART to protect and encrypt your
products.

PART1FundamentalSection
All ROCKEY6 SMART special features, functions and basic concepts for software protection will
be introduced in this chapter, providing you with a general overview on this product.

PART2ApplicationSection
After completing this chapter you will know how to use Keil u Vision2 to compile the kernel of your
encrypted application and choose the corresponding API function. You will also learn the development
procedure of ROCKEY6 SMART.

PART3AdvancedSection
This chapter will introduce RSA, DES encryption algorithms and how to work with APDU and COS
(Card Operation System). After completing this chapter you will not only upgrade to a further level of
using ROCKEY6 SMART to protect your application but you will also master the advanced encryption
management.

ROCKEY6 SMART User Manual V1.3

v
PRENOTE
(1) The initial super password of ROCKEY6 SMART demo dongle is 8 bytes: FF FF FF FF FF FF
FF FF. The retry times limit is 15 i.e. the smartcard will be locked after 15 times continuous
unsuccessful verifications. If the dongle is locked, it must be returned to the manufacturer to be
repaired. Super password needs to be verified before the advanced operation like generating or
deleting executable files or internal files, formatting dongle, generating remote update file etc. Please
keep the super password safe. Do not include it to the encrypted program and never show it to others.

If change the super password to eight 0x00 (i.e. 00 00 00 00 00 00 00 00), the smartcard will be
locked. In this case, no files can be imported to the dongle any more. Only the executable files can be
called. Using initial super password in development is recommended. This can prevent the smartcard
being locked unexpectedly. Once the smartcard is locked, there will be no way to unlock it, even the
manufacturer can not fix the password or unlock the dongle. This design can guarantee maximum
security performance.

(2) When ROCKEY6 SMART is inserted, the flash disk icon will be displayed in the task bar. User
can unplugged the dongle directly when finish using.

(3) When attached ROCKEY6 SMART dongle to the computer, if the light of the dongle blinks, this
indicating a connection error. Please check the operating system status, the USB port connection. In
Windows98 system, please check is the driver installed properly. Switching to a different USB port or
test with a flask disk may help to find the problem.

(4) The memory space of ROCKEY6 SMART dongle is about 64 KB. If FLOAT library and
RSA_DES library are loaded, there will be about 28 KB left available. The space is located at EEPROM
with 500,000 rewritten times. The rest of memory is located at FLASH with 20,000 rewritten times.
ROCKEY6 SMART User Manual V1.3


vi
Reading times is not limited. RSA_DES library costs about 14 KB space and FLOAT library costs about
21 KB space.

(5) There are three ways to load executable programs to the dongle:
Use Download to Flash Memory button in KEIL
Use ROCKEY6 SMART IDE tool to import BIN file generated by hexbin.exe
Use ROCKEY6 SMART API to import the program

(6) An advice for programming, one process should only call open and close dongle once. When
start the process, open the dongle, and when close the process, close the dongle. For multi-process
and multi-entry operation, please add mutex mechanism to the design.

(7) C51 program has three ways to accept external inputs. When acquire BYTE input and store it in
integer variable, please alternate the order of the inputted bytes. The output of C51 program is in BYTE
order, please also alternate the order of integer variables (refer to sample 11). For double float variable
(DOUBLE type, 8 bytes), the order need not to be changed.

(8) If do not want the files be listed with ROCKEY6 SMART IDE, there are two ways to prevent this:
Set executable files attribute as internal executable. File will only be listed after verified super
password. Using APDU filter, software vendor can define the APDU command of listing files (refer to
chapter 12.4).

(9) Management code is composed of four parts (Zone, Distributor, User1, and User2). This
information is preset during the manufacturing. User cannot change them. Management code is used
for sales management. Different software vendors have different management code. User cannot by
the dongle from other vendor which has the same management code. It is the important information to
identify dongles (refer to sample18).
ROCKEY6 SMART User Manual V1.3


vii

(10) Remote update cipher text file is related to the user code and update password (if password is
set). This means the same plain text file can generate different cipher text with different user code or
remote update password (refer to chapter 5.2 Secure File Transfer).

(11) Virtual card cannot stimulate all the functions of real card, for example RSA_DSE function,
C51 program calling other C51 programs. Developing applications with real card is recommended.

(12) When calling by external API, executable programs are identified by their file name, not the file
ID. Using same file name and file ID is recommended. For example, file ID: 0x1008 will have the file
name 1008. File name can not he overlapped.

(13) One note for using counter of ROCKEY6 SMART, if setting the specific number of times,
please do not process data until the counter decline to 0. It is supposed to start operation while number
is greater than 0, or the counter of ROCKEY6 SMART will be un-reused for the user, and must be
returned to the manufacturer to be initialized for the second time.

(14) Please mention the following points in RSA encryption/decryption:
Key length is measured by bits. Only 512 bits and 1024 bits RSA keys are supported
Do not set the name of public key file. Please leave it empty.
The default value of e is 65537. This value cannot be changed.
When encrypt the data, please set source datas highest byte to 0 in order to prevent overflow.

(15) It is important to keep the version in match mode if loading RSA_DES and FLOAT two
libraries into a blank ROCKEY6 SMART, that is to say, the version of two files float.bin and rsa_des.bin
in the <TOOLS>directory of SDK must be in conformity with the COS and hardware of ROCKEY6
SMART.
ROCKEY6 SMART User Manual V1.3


viii
(16) If your application is running on Win2000 or above Operating systems with the user role, it is
recommended to use the libraries in <API32\NT Service> directory of SDK, and referring to the
samples in <Samples\Solution\NT Service> directory. (Concerning applications running on Win98,
directly using Dic32u.dll is ok in respect that there is no separate role under Win98 systems, such as
Administrator, users...). Rockey6SmartSvc.exe is a service program; it is required to install it using
APIs provided by Dic32Svc.dll:

Install Service:
I nst al l RYSSer vi ce( LPCTSTR l pFi l ePat h)
/ / l pFi l ePat h poi nt s t o t he pat h t hat Rockey6Smar t Svc. exe l ocat es, such as
" C: \ \ Rockey6Smar t Svc. exe" ; i f you copy t he . exe f i l e under <Syst em32>
di r ect or y, i nput " Rockey6Smar t Svc. exe" wi t hout modi f i cat i on i s OK i n such case.
Start Service: StartRYSService ( )
Stop Service: StopRYSService ( )
Delete Service: RemoveRYSService ( )

After service installation, the "ROCKEY6SMART SERVICE" item will appear in the service list with
following path: Control Panel -> Management -> Service, and start automatically with each time
computer starting. Same with Dic32u.dll, calling APIs provided by Dic32Svc.dll is also needed for your
application to run, with a couple of points to be noted:

The maximum size for Input/Output buffer of service program is 2048 byte, for example:
char cmddat a[ 2048] ;
/ / buf f er f or command
char buf f er [ 2048] ;
/ / buf f er f or user

ROCKEY6 SMART User Manual V1.3


ix
NULL is not acceptable to service program, for example:
char t emNul l [ 20] ={0} ;
memset ( t emNul l , 0 , si zeof ( t emNul l ) ) ;
DI C_Set ( cmddat a, DI R_I D, BY_VALUE, 0x1000, t emNul l ) ;
/ / The l ast par amet er of BY_VALUE i s usel ess f or t he macr o, a poi nt er but
" NULL" may be pr ovi ded at such case

String-like parameter cannot be accepted by service program in straight way, which need to be
copied and stored at the location pointed by a variable and then pass in.
st r cpy( buf f er , " Di r 1" ) ;
/ / st r i ng t o be copi ed and st or ed i n memor y poi nt ed by var i abl e
DI C_Set ( cmddat a, DI R_NAME, BY_ARRAY, 0, buf f er ) ;
/ / copy " Di r 1" f r ombuf f er t o t he memor y poi nt ed by cmddat a

(17) After encryption, we suggest user to create an executable file for Rockey6Smart with the
following method (refer to Section 12.4 for detailed information). Therefore, it is unable to list the file
directory inside of the ROCKEY6 SMART whether using the tool IDEII.exe in <Tools>directory or
calling APIs. Compile code below by KEIL with .bin file output.
#i ncl ude sys_api . h"
voi d mai n( )
{
wor d sw = 0x6982;
set _r esponse( 2, &sw) ;
exi t ( ) ;
}

ROCKEY6 SMART User Manual V1.3


x
And generate the executable file, applied "00B2" as name and ID, inside of the ROCKEY6 SMART
from the well-compiled .bin file by APIs invocation.

(18) If using multi-thread on the client-side for ROCKEY6 SMART, the module number of each
thread logged on should be different to each other, i.e. the thread and the module number

(19) Code for calling APIs can be obtained by the GenCode.exe tool in the <TOOLS>directory on
SDK; similarly, refer to ErrorLookup.exe in the same directory you can look up the error code with
particular description

(20) Attention for C51 programming is expatiated in the Appendix B.

(21) While running on Vista OS, it is quite important to select "running as the administrator" on the
popup dialog after right-click the service program icon, or you can change the running mode of this
application to Administrator rights (please get detail from vista user manual).

ROCKEY6 SMART is a newly developed powerful security product from FEITIAN Technologies. It
is a smart card kernel based USB device that combines software protection dongle and smart card
technologies in a very small form factor. It supports multiple applications including software protection,
personal identification and authentication, data security and protected electronic transactions. This
manual will guide you on how to use ROCKEY6 SMART to protect and encrypt your products.






ROCKEY6 SMART User Manual V1.3


xi
TABLE OF CONTENTS
PART 1 FUNDAMENTAL SECTION 1
CHAPTER 1 ROCKEY6 SMART SOFTWARE PROTECTION SOLUTION 3
1.1 ROCKEY6 SMART INTRODUCTION3
1.2 HOW TO PROTECT SOFTWARE WITH ROCKEY6 SMART 4
1.3 HOW ROCKEY6 SMART PROTECTED SOFTWARE5
CHAPTER 2 ROCKEY6 SMART INSTALLATION AND REMOVE 7
2.1 INSTALLATION7
2.2 REMOVAL10
2.3 INSTALL AND REMOVE DRIVER10
CHAPTER 3 INTEGRATED DEVELOPMENT ENVIRONMENTS (IDE) 12
3.1 IDE INTRODUCTION12
3.2 WRITE FILES INTO ROCKEY6 SMART17
CHAPTER 4 CARD OPERATION SYSTEM 19
4.1 MODULE19
4.2 DATA FILES AND DIRECTORIES20
4.3 EXECUTABLE FILE21
4.4 FILE CATEGORIES22
4.5 FILE SECURITY LEVEL 23
4.6 FILE ATTRIBUTES 24
4.7 SECURITY MECHANISM25
CHAPTER 5 REMOTE MANAGEMENT 27
5.1 UPDATE TAG28
5.2 UPDATE FILE33
ROCKEY6 SMART User Manual V1.3


xii
5.3 REMOTE MODULE MANAGER42
5.4 INSTRUCTION OF REMOTE UPDATE ON CLIENT-SIDE46
CHAPTER 6 PRODUCTION MANAGEMENT 48
PART 2 APPLICATION SECTION 54
CHAPTER 7 DEBUG WITH ROCKEY6 SMART SIMULATOR 55
7.1 CONFIGURE KEIL IDE55
7.2 CREATE A PROJ ECT 55
7.3 PROJ ECT CONFIGURATION 56
7.4 DEBUGGING62
7.5 QUIT63
7.6 SAMPLE DEBUGGING63
7.7 WRITE PROGRAM TO THE REAL CARD64
7.8 SUMMARY 64
CHAPTER 8 ROCKEY6 SMART ESSENTIAL 65
8.1 DEVELOPMENT INTRODUCTION65
8.2 FUNDAMENTAL USAGES65
8.3 CREATING C51 PROJ ECT68
8.4 CREATING AN EXECUTABLE FILE IN THE DONGLE68
8.5 EDITING AND ENCRYPTING DONGLE INTERCOMMUNICATION PROGRAM 71
8.6 CORE CODE SELECTION73
8.7 SUMMARY 74
CHAPTER 9 ROCKEY6 SMART COMMUNICATION API REFERENCE 75
9.1 INT DIC_FIND()75
9.2 INT DIC_FINDBYMGRCODE(VOID * PMGRCODE)76
9.3 INT DIC_OPEN (INT HIC, CHAR* READER_NAME) 76
ROCKEY6 SMART User Manual V1.3


xiii
9.4 INT DIC_CLOSE(INT HIC)77
9.5 INT DIC_COMMAND(INT HIC, INT CMD, VOID* DATA)78
9.6 INT DIC_GET(VOID* TARGET, INT P1, INT P2, CHAR* PSTR);86
9.7 INT DIC_SET(VOID* TARGET, INT P1, INT P2, INT P3, CHAR* PSTR) 90
9.8 INT DIC_GETVERSION(CHAR* VER) 90
9.9 RETURNED ERROR CODE 91
9.10 AUTHORIZATION94
CHAPTER 10 API REFERENCE AND SAMPLES 97
10.1 API REFERENCE 97
10.2 SAMPLE01 FUNDAMENTAL FRAMEWORK 98
10.3 SAMPLE02 TRAVERSING DONGLES 100
10.4 SAMPLE03 DYNAMIC LINKED MODE101
10.5 SAMPLE04 GET MANUFACTURE AND VOLUME INFORMATION104
10.6 SAMPLE05 GET MANUFACTURE TIME, HARDWARE SERIAL NUMBER, SHIPPING TIME, AND COS VERSION106
10.7 SAMPLE06 GET ZONE CODE, RESELLER CODE, USER CODE 1 &USER CODE 2107
10.8 SAMPLE07 RANDOM NUMBER108
10.9 SAMPLE08 SUPER PASSWORD109
10.10 SAMPLE09 DIRECTORIES AND FILES111
10.11 SAMPLE10 REMOTE UPDATE115
10.12 SAMPLE11 WRITE AND EXECUTE PROGRAM115
10.13 SAMPLE12 DOUBLE-PRECISION POINT CALCULATION116
10.14 SAMPLE13 SECURE FILE TRANSFER 116
10.15 SAMPLE14 DES AND 3DES ENCRYPTION AND DECRYPTION116
10.16 SAMPLE15 RSA ENCRYPTION AND DECRYPTION117
10.17 SAMPLE16 COUNTER USAGE118
10.18 SAMPLE17 READING THE REMAINING SPACE 119
10.19 SAMPLE18 UNLOCK THE DONGLE ACCORDING TO THE MANUFACTURE ID119
ROCKEY6 SMART User Manual V1.3


xiv
PART 3 ADVANCED SECTION 120
CHAPTER 11 SYSTEM CALL FUNCTION USAGE 121
11.1 MEMORY MANAGEMENT122
11.2 FUNDAMENTAL FRAMEWORK 123
11.3 FILE OPERATION 125
11.4 INVOKE EXECUTABLE PROGRAMS128
11.5 SYSTEM INFORMATION AND SECURITY MECHANISM130
11.6 RSA ENCRYPTION AND DECRYPTION133
11.7 DES ENCRYPTION AND DECRYPTION135
11.8 OBTAIN RANDOM NUMBER138
11.9 FLOAT FUNCTION LIBRARIES USAGE 139
11.10 RELEASE MANAGEMENT141
CHAPTER 12 ADVANCED FILE SYSTEM APPLICATION 145
12.1 FILTER FILE145
12.2 APDU145
12.3 ROCKEY6 SMART APDU COMMAND SET147
12.4 FILTER APDU 152
CHAPTER 13 COS SYSTEM CALL REFERENCE 159
13.1 FILE OPERATIONS159
13.2 SECURITY MECHANISM163
13.3 SYSTEM SERVICES164
13.4 SYSTEM INFORMATION 166
13.5 DOUBLE PRECISION FLOAT CALCULATION168
13.6 FLOAT POINT LIBRARY EXPANSION 171
13.7 ENCRYPTION AND DECRYPTION FUNCTIONS176
13.8 TIMER AND COUNTER180
ROCKEY6 SMART User Manual V1.3


xv
13.9 OTHERS181
13.10 SYSTEM FUNCTION CALL ERROR CODE182
APPENDIX 183
APPENDIX A GLOSSARY OF TERMS183
APPENDIX B TERMS185






ROCKEY6 SMART User Manual V1.3


1

PART 1 Fundamental Section
All ROCKEY6 SMART special features, functions and basic concepts for software protection will
be introduced in this chapter. You will obtain a general overview on ROCKEY6 SMART.

Chapter1,ROCKEY6SMARTSoftwareprotectionsolution
In this chapter you will learn the specifications and the functions of ROCKEY6 SMART, and theory
of protecting your application. After completing this chapter, you will obtain a general overview of
ROCKEY6 SMART.

Chapter2,ROCKEY6SMARTInstallationandRemoval
Before using ROCKEY6 SMART, you should first install the ROCKEY6 SMART Developer Kit. This
chapter will explain the procedure to both install and remove the ROCKEY6 SMART Developer Kit.

Chapter3,IntegratedDevelopmentEnvironment(IDE)
In this chapter you will learn the following,
How to manage the card and file inside of the card; how to format and set the password;
Manage to download executable files;
How to implement the remote management;

Chapter4,CardOperationSystem(COS)
ROCKEY6 SMART is based on IC card technology. COS regards the electrical chips as a small
virtual computer. ROCKEY6 SMART has its own CPU and file system.

Chapter5,RemoteControl
Remote control involves three parts; remote update control, secure file transformation and remote
ROCKEY6 SMART User Manual V1.3


2
model control. You can update your software and the encryption algorithm, and also manage the user
model (shut or open the corresponding model) securely.

Chapter6,ManufacturingManagement
You will learn how to batch program ROCKEY6 SMART in this chapter.












ROCKEY6 SMART User Manual V1.3


3
Chapter 1 ROCKEY6 SMART Software
Protection Solution
1.1 ROCKEY6 SMART INTRODUCTION
The ROCKEY6 SMART dongle is another powerful product from FEITIAN Technology Co., Ltd. It
is the result of research and insight gained from the development of the ROCKEY5 dongle, ePass1000,
ePass2000 and Feitians experience in driverless technology. The ROCKEY6 SMART dongle is a USB
device which is based on IC card technology utilizing encryption technology. It can be utilized in many
areas such as software protection, authentication, and electronic business and information security.

ROCKEY6SMARTFeatures:
Security at Hardware Level
The ROCKEY6 SMART is based on smart card technology. Smart cards are widely used in the
banking and financial sectors where security is of paramount importance. Smart card hardware is
engineered to prevent reverse engineering and specialized analysis, used by hackers and others who
seek to crack security schemes. Smart cards integrate modules such as CPU, RAM, EEPROM and
FLASH and are essentially a mini-computer on a chip, providing a powerful and versatile platform for
developing complex and powerful security programs.

Hardware Compatibility
ROCKEY6 SMART consists of a USB card reader and a specially programmed smart card.

Security at Software Level
The target programs kernel algorithms and data may be transplanted and executed inside the
ROCKEY6 SMART User Manual V1.3


4
smart cards protected environment. The transplanted code operates under the management of the
smart card operating system and forms a miniature-computing environment that runs in parallel to the
main computer. The ROCKEY6 SMART environment and the main computing environment exchange
data through the USB port. The probability of a successful hack of this system can be reduced to near
zero if a reliable solution plan and certain sophisticated algorithms are correctly adopted.

Software Compatibility
ROCKEY6 SMART fully supports the ISO7816 smart card standard as well as specific extensions
to the standard. This system will be familiar both to users of software protection dongles as well as
those familiar with smart card technologies.

Flexibility
Many advanced administrative functions (such as Remote Update Management) have been
incorporated for software developers. All security requirements are accomplished through a set of basic
functions provided with the ROCKEY6 SMART system. Developers may build their own complex
protection plans based on the ROCKEY6 SMART function set.

1.2 How to Protect Software with ROCKEY6 SMART
By using ROCKEY6 SMART, you can migrate a portion of the target application into the ROCKEY6
SMART memory, with the rest residing on the computer. The applications which are migrated into the
ROCKEY6 SMART are called external programs. The external program will not be loaded into the
main computer memory during execution. External programs are stored in Electrically Erasable
Programmable Read Only Memory (EEPROM). The main program can call the external programs
separately it cannot call them simultaneously. External programs can also call one another. The target
application cannot function properly without the dongle attached.
ROCKEY6 SMART User Manual V1.3


5

Figure11HowROCKEY6SMARTProtectsSoftware

1.3 How ROCKEY6 SMART Protected Software

The ROCKEY6 SMART dongle is a driverless device. You can connect the dongle directly to the
computer without having to install any USB device drivers.








Figure12ROCKEY6SMARTProtectedSoftware

1. When the main program execution reaches an external program, the program call command
ROCKEY6 SMART


External program
Application
Algorithm& data
ROCKEY6
SMART
USB
ROCKEY6 SMART User Manual V1.3


6
is sent to ROCKEY6 SMART along with the required parameters.
2. ROCKEY6 SMART responds to the command of the main program, executes the related
external program and returns the result back to the main program. ROCKEY6 SMART remains in
waiting status until the next command.
3. You will obtain the results from the dongle as if it were executed all on the computer;
however the procedure runs in the dongle and never loads into the computer.
ROCKEY6 SMART User Manual V1.3


7

Chapter 2 ROCKEY6 SMART Installation and
Remove
On the ROCKEY6 SMART disc, you will find the directory ROCKEY6 SMART SDK. See details in
Appendix B2 ROCKEY6 SMART SDK. Double-click setup.exe to start your installation.
2.1 Installation
Step1: Welcome Window
After double clicking setup.exe, the following window is shown:

Figure21WelcomeWindow

Step 2: Agreement
ROCKEY6 SMART User Manual V1.3


8
After you choose [I Agree] the agreement, click [Next] to continue:

Figure22Agreement

Step 3: Select Installation Model and Components

Figure23Selectthetypeofinstallation

ROCKEY6 SMART User Manual V1.3

9
- If Typical option is chosen, the program will automatically install the ROCKEY6 SMART API
library, ROCKEY6 SMART IDE and help documentation for you.
- If Compact option is chosen, the program will only install the ROCKEY6 SMART API library and
developer manual.
- If Custom option is chosen, the user can select the components needed to be installed.

Step 4: Install Location

Figure24PathSelectionforInstallation

Step 5: Installation finish

Once completing the installation, click Finish button to quit.
ROCKEY6 SMART User Manual V1.3


10

Figure25CompleteInstallation
2.2 Removal
There are two methods to remove the installation. One is from Control Panel >Add or Remove
Programs where you select ROCKEY6 SMART; another is from start >Programs >uninstall
ROCKEY6 SMART.
2.3 Install and Remove Driver
ROCKEY6 SMART is a USB device that works smoothly with Windows and Linux systems. If
ROCKEY6 SMART is plugged into the USB port, the system will automatically detect that the drivers
are not installed in the computer and initiate the driver setup wizard.

For Windows98 systems, a Win98 installation disc is required for the driver installation. For other
ROCKEY6 SMART User Manual V1.3


11
operating systems such as Windows Me/2000/XP, Windows 2003 server and Vista as well, the driver
setup wizard will automatically start.
ROCKEY6 SMART User Manual V1.3


12

Chapter 3 Integrated Development
Environments (IDE)
The Integrated Development Environments has the following features:
Card management, it includes formatting, password and volume initialization and updates etc.
Executable file management for downloading
Remote control (for details read Chapter 5)
3.1 IDE Introduction

Figure31IntegrateDevelopmentInterface
ROCKEY6 SMART User Manual V1.3


13

From Figure 3-1, the standard IDE includes menu bar, tools bar, project bar, edit window, compile
bar and status bar. Here, we only provide an example for Project bar, Tools bar, Detected Device
window and Virtual Device window.

Menu Bar
Menu bar encompasses all the commands to perform all IDE functions. The following table lists all
items from the menu bar. Menu items are dynamically designed, meaning that they appear only when
they need to. Therefore users may view different menu items according to cases. Their functions will be
discussed in the main menu section.

Some menu items in our IDE example:
Table31FileMenu
New C51 Project Create a new project
Browser Real Devices Browser Plug-in Devices
New Virtual Device Create a new virtual device
Open Virtual Device Open a virtual device file
Recent Files List recently opened files
Quit Quit program
Table32View
Toolbar Display or hide Tools bar
Statusbar Display or hide Status bar
Device Tree Display or hide files tree of the device
Table33CardOperation(Appearsonlyatdevicewindow)
Refresh Refresh current active devices
Format Format device file system
ROCKEY6 SMART User Manual V1.3


14
Modify Password Modify super password for device system
Remote Update
Management
Create and test remote update password
Remote Module
Management
For manufacture remote module management
Generate Cipher text file Generate a cipher text file
Generate Plain text file Generate a plain text file
Card Information Display information for manufacturer, hardware and
management ID
Burn Real Card Burn the content of selected virtual device into real card
Verify the Super Password Switch to the state for verifying the super password to
display the internal files
Cancel Verification State Cancel the state for verifying the super password to hide
the internal executable files
Import File Import disc file into device
Export to Disc Export file to the disc
New Directory Create a new subdirectory under the file system of the
device
Run Run the selected executable file
Table34Tools
Binary Code ->Source
Code
Convert binary code to arrays in C,VB source code
Table35Windows(Appearsatsubwindowactivestate)
Cascade Cascade the windows
Tile vertical Arrange windows by column without cascade
Tile horizontal Arrange windows by row without cascade
ROCKEY6 SMART User Manual V1.3


15
Close Window Close current active windows
Close All Close all active windows
Previous Window Switch to previous window
Next Window Switch to next window
Table36Help
About ROCKEY6 SMART
IDE
Display software information, version number, copyright,
API version number and hardware information


Tools Bar
Tools bar may be displayed differently each time according to distinguished active window types.
Table37AllButtons

Open a virtual device file

Browse connected devices

Display software information, version number, copyright, API version
information and hardware information

Table38Usefulbuttonsinsysteminitialstate(beforeactivewindowpoppingup)

Create a new C51project

Table39Usefulbuttonsatthestateofeditingwindowisactive

Save active content

Cancel previous modification
ROCKEY6 SMART User Manual V1.3


16

Cut the selected subject and save it to the clip board

Copy the selected subject and save it to the clip board

Paste the saved subject from clip board
Table310Usefulbuttonswhenthestateofthedevicewindowisactive(includesreal
devicesandvirtualdevices)

Import files from the disc into the device

Export files from the device to the disc

Create a new sub directory in the device file system directory

Copy the selected file subject and put it on the clip board

Paste the content of file subject from the clip board

Delete file or directory. When you delete a directory, please make sure the
directory is empty before its deletion.

Display the content of the selected device file.

Switch to the state of super password verification, in order to display the
internal files.

Cancel the state of super password verification, in order to hide internal
executable files.

Modify the password for the device file system.

Refresh the devices.

Display manufacturer information, hardware information and management
code.

Run the current executable file. (If it is an executable file)
ROCKEY6 SMART User Manual V1.3


17

3.2 Write files into ROCKEY6 SMART
After the software system is successfully initialized, the user can write files into the ROCKEY6
SMART. The initialization of ROCKEY6 SMART includes setting up the label, manufacturer information
and super password. The user can modify the default values by simply formatting the ROCKEY6
SMART.

Figure 3-2 displays the formatting window for ROCKEY6 SMART. It is different from setting up the
virtual file system. The label and manufacturer information in the virtual file system contains default
values that cannot be modified.

Figure32FormattingROCKEY6SMART

Before formatting, select the necessary modules for loading. Writing a file into the ROCKEY6
ROCKEY6 SMART User Manual V1.3


18
SMART is easy, similar to copying a file between folders. It can be done by using the following
methods:
Ctrl +C (Copy) then Ctrl +V (Paste) or right clicking the mouse and selecting Copy and Paste.
This method is commonly used for adding a file to the dongle or copying an executable file from one
virtual card to another.

- Bulk Burn Function
The difference between directories in a PC and ROCKEY6 SMART is that the executable file in the
real card can only be deleted and not be read. Some manipulations require super password verification
like deleting files, however some other manipulations like copying one file from one ROCKEY6 SMART
to another, or viewing a text file and performing an executable file do not.
ROCKEY6 SMART User Manual V1.3


19

Chapter 4 Card Operation System
4.1 Module
ROCKEY6 SMART uses an IC card, integrated circuit chip, as the core for its algorithmic execution
and storage medium. The design of this cards operating system enables the entire device to work as a
virtual mini computer which has its own CPU and file system.

Figure41ICcardstructure

The EEPROM works similar to a computers hard drive which can be used for storing programs
and data. All files in the ROCKEY6 SMART are stored in EEPROM, with these files being only read and
written by its manufacturer or its integrator but not End Users. End Users are unauthorized to access
data in the EEPROM. There is only one file system in the EEPROM with every operation being
performed in terms of file-operations (open, close, read, write, delete etc.). The EEPROM could be
ROCKEY6 SMART User Manual V1.3


20
treated as a logical driver in the PC with the entire file system marked to a volume (root directory), just
likes a logical driver in drive C:\ . Common operations can be performed in the logical driver, such as
making directories, and writing and removing files, however, some operations require super password
verification.

The RAM area is similar to a computers memory where the application input, output and
temporary variables are store.

COS (Card Operation System) controls the entire IC card system. In the process of communication
between ROCKEY6 SMART and the host computer, ROCKEY6 SMART always passively receives
instructions from the host computer, never visa-versa. All messages from the host computer are
interpreted and executed by the COS.
4.2 Data Files and Directories
The file system contains data files, executable files and directories. In this section, we explain the
data files and directories.

Data files and directories are distinguished by a 2-byte ID and located in the same name space. In
the root directory, some IDs are held by the system default directories and files. These IDs are 0000
(system hold), 2F01 (ATR files - includes manufacturer information), 3F00 (volume), and 3FFF (current
directory). Any one of above four IDs holds a complete name space. Except for the above mentioned
IDs, all other IDs can be used freely.

Volume and manufacturer information can only be set and modified when the ROCKEY6 SMART
is formatted. The content of manufacturer information is 15 bytes long and written by the manufacturer.
If the manufacturer chooses not to input any data, then COS will automatically fill them with default
ROCKEY6 SMART User Manual V1.3


21
values. The volume is 16 bytes long and also set by the manufacturer.
4.3 Executable File
All executable files are recognized by their IDs and file names. The IDs for executable files,
directories and data files use the identical name space. We suggest users allocate IDs starting from
0x1000 when the data files and directories are created. This will avoid ID conflicts.

Naming an executable file (file name is 16 bytes long) is a little complex. An executable file is
usually selected according to its name. The following explanation covers this technical detail. For those
who are not interested in this may want to jump to Section 4.4 directly.

According to ISO7816-4, we assign the following rules for naming the executable files.

File name is xxyy, 2-byte. x or y is a hexadecimal number. The following is the range for xx
Table41ValueRange

The following rules are used for the value range of yy.
1. Cannot be a 6x or 9x
2. Cannot be odd numbers
3. 66 is a reserved wildcard character. Please do not use it due to its complexity.

The rest are also reserved values for ISO7816-4. They are possibly used by executable files, but
ROCKEY6 SMART User Manual V1.3


22
still complicated when using them.

All executable files are stored in the root directory. In contrast, data files can be stored anywhere in
the directory. An error message of COS system will prompt if moving executable file into the
subdirectory, and accordingly, the executable file cannot be touched by system this way. In the COS
system, ONLY executable files in the root directory can be executed.
4.4 File Categories
Directory categories and file categories are symbolized by a byte (0x00 0xFF) named File
FCLA. It is initially defined by the manufacturer. All files with the same FCLA can be treated as files
from the same product. With the restriction of FCLA, all executable files in the ROCKEY6 SMART can
only read, write and create the data files with the same FCLA. The following rules are applied for FCLA:
0xFF represents a null category, in which all its data files can be accessed by any type of
executable files, but all executable files in this category can only access the data file with 0xFF.
The category of the root directory is also a null category.
All files with the same category constitute a relatively independent subsystem. All data files of a
null category are public data; and all executable files of null category are public programs.

FCLA is commonly applied for product management. If a manufacturer is developing many
products, or a number of manufacturers are cooperatively working on the same product, FCLA would
be good to apply. For example, if a dongle needs a set of application software, then set FCLA to FF.
All files under the same directory and subdirectory would be set to the same FCLA; and their
accessibilities controlled by security level.

File category is recorded in the system with 1-byte length called system current file category.
When system current file category is executing file selection or fetching the executable files in the
ROCKEY6 SMART User Manual V1.3


23
dongle, it can switch according to the following rules:

(1) If the target file is a null category file, then the system current file category will keep its category
unchanged; otherwise they will switch to the category of the target executable file.
(2) Whenever the category switching occurs, the system current security level will be reset to 0.
(3) After resetting the dongle, the system current file categorys default value is 0xFF (null category).
Another important usage for FCLA is filtering files; however, this topic is beyond the scope of this
manual. For further information, please contact us.
4.5 File Security Level
Beside category, every file has a security level for controlling the access to files with the same
category. Namely, security level is set for the files with the same category.

In most cases,security level combines 4-bits of low order byte (from least significant byte), and
attribute (4-bit of high byte (from most significant byte)) into a byte. There are 16 distinguished states in
total. In those states, 0 is the lowest level and 15 is highest.

COS also has its own security level. At run time, it is recorded by a byte. This security level has to
be updated by the ROCKEY6 SMART internal executable file (via system fetching).

However, there is a constraint executable files cannot grant COS security levels higher than itself.
Executable files can only access (read, write or create) data files with a lower security level. When
finished, they can set the security level to 0.

To perform a higher security level management, one can set all security levels to 0.

ROCKEY6 SMART User Manual V1.3


24
4.6 File Attributes
There are five kinds of file attribute of ROCKEY6 SMART: Normal, Internal, Up-to-Ignore, Directory
and Executable. A directory or file can have many attributes.
- Normal is the default attribute for a file without any customized settings.
- Executable indicates the file is executable for COS. However, those files have to be allocated at
the ROCKEY6 SMART root directory and can only be created or deleted after successful super
password verification.
- Dir means it is a sub-directory. If this attribute is set, the other attributes will be ignored.
- Up-to-Ignore only applies for internal files of ROCKEY6 SMART. It represents an executable file
that can only be executed on the condition that the system security level is lower than or equal to the
executable file security level. Otherwise the executable file cannot be executed.
- Internal means that if it works for a data file, the data file can only be accessed by the
- ROCKEY6 SMARTs internal executable files. It can be deleted by the external program only after
successful super password verification. However in either case, it cannot be read or written by the
external program. If it works for an executable file, the executable file contains hidden attributes. If a
user lists all directory files without supplying successful super password verification, all executable
files with hidden attributes cannot be shown. This is an effective way to protect executable files.
- Only after successful super password verification can executable files and internal files are created
by using the API.

For implementation, use 1-bit high 4-length to represent the attributes
Table42Fileattributessignandmacro
Attributes Sign Macro
Normal 0x00 NORMAL
Execute 0x10 EXEC
Directory 0x20 DIR
ROCKEY6 SMART User Manual V1.3


25
Up-to-Ignore 0x40 UPIGNORE
Internal 0x80 INTERNAL

4.7 Security Mechanism
Core of the security mechanism is that based on the system security level which has 16 different
levels. The combination of the system security level and the file security level control access
permissions to all the files on the card. The COS will only perform operations on a particular file if the
system security level is greater or equal than the security level set for the particular file. There are two
different techniques to change the system security level: verify the super password or perform an
executable file on the virtual machine.

The COS security mechanism includes three sub-systems. They are:

Part1,Globalsecurity
One 8-byte super password is adopted as the global security policy. Feitian, the ROCKEY6
SMART manufacturer, initially sets and provides the super password to the software developer. The
super password can be modified or abandoned by the software developer. After successful verification
of the super password, the system security level is set to its maximum value and all normal (excluding
internal) data files in the card can be read or updated. Executable files can only be selected or deleted.
The super password is always required for creating the executable files. If the super password is set to
all zeros, the developer can no longer modify or verify it -this operation disables the super password
and permanently eliminates access to super user privileges. Be careful before invoke this operation.

Part2,Filesystemsecurity
There are two parts to the file system security: (1) file classification application, which allocates the
ROCKEY6 SMART User Manual V1.3


26
files into different kinds of groups. The security levels of the groups are independent. Furthermore the
file classification limits the program in the virtual machine by not allowing access to other files in
different classifications. (2) On the other hand, the executable files must have a security level that is
greater or equals to any data file that it attempts to run.

Part3,COSsecuritylimits
When a running executable file needs to change the system security level, COS will limit the
system security left to equal or less than the program security level.



ROCKEY6 SMART User Manual V1.3


27

Chapter 5 Remote Management
Dongle was used to protect software program by SW vendor with general acceptance; on the other
side, owing to being a physical goods, the selling and updating of the hardware dongle can only be sent
by post but through Internet, which is available for the pure software product. It is quite imperative, in
such case, to achieve the function of remote update with the aid of hardware dongle.

Three types of remote update were integrated into the ROCKEY6 SMART, which are Update Tag
(UT), Update File (UF), and Module Manager (MM).

Update Tag means to change the remote update tag of client-side dongle with secure method,
intended to make internal program on client-side could manage to handle different actions based on the
judgment of this tag; else to implement update combined with other two methods described below.

Update File implies to a full procedure of encryption/decryption across the server-side and
client-side, particularly, encrypts the plain-text file first and sent it to user, and on the client-side,
restore the Cipher-text file inside of the dongle back to the original plain-text one. Within such
scheme, user may replace any file inside of the ROCKEY6 SMART in the direct way, which is quite
powerful and popular for use, and was described later with stress.

Module Manager focus on executable files only, the SW vendor, recurring to some secure methods,
may control the running status of one or a set of .exe file on client-side correspondingly; secure file
transfer, in a similar way, can be used to implement this feature.

ROCKEY6 SMART User Manual V1.3


28
5.1 Update Tag
Update Tag is a basic feature that may be utilized by ROCKEY6 SMART developers to implement
remote updates of their software protection and licensing systems. UT is based on one time
passwords, that is to say, key of each update operation is unique and can only be used once.
Two relative concepts are involved in the Update Tag; they are New Password, and New Tag
described below.

The remote update password---New Password is provided by the software manufacturer to the
end user to verify and update the dongle.

The remote update tag -- New Tag, should not be confused with the update password as this is
the information set by the software manufacturer for identifying the current software update status. We
recommend you mark the software version, thus providing the ability to recognize the version of
software the user intends to update. This is a 32-bit number, and its highest bit (0x80000000) is used to
show whether the hardware ID is used or not. If the bit is 1, the update password is related to the
hardware ID of the dongle; if it is 0 it means the update password has nothing to do with the
hardware ID and only makes reference to the previous update password. One Time Password
simplifies update maintenance of the software manufacturer.

Additionally, the New Tag and New Password provided to the user are related to each other.
The user cannot modify either of the two. If the highest bit of New Tag is 1, the update password is
only valid for a specific dongle. In the information the user offers to the software developer, only the
hardware ID and the previous update password are necessary. The last New Tag is merely a
reference to the software manufacturer and it does not affect the next update information. The software
manufacturer should set a new New Tag as the update mark different from the previous ones for each
update operation.
ROCKEY6 SMART User Manual V1.3


29
The UT operation involved several steps that are described as follows:
1. The software vendor must first initialize the ROCKEY6 SMART dongle to set the Initial Remote
Update Tag (IRUT) and Initial Remote Update Password (IRUP). Here, we suggest you to set initial tag
and password for later use even if you do not plan to use this feature for the moment. The IRUP cannot
be set as a single F in all size; similarly, a single 0 in all size is unacceptable for the IRUT value input.
See Figure 5-1 for detail:

Figure51

This step is the initial step of SW vendor before handing the ROCKEY6 SMART to the end user; in
addition, since its a one-time-only operation, the reset of IRUP is based on the reformat of ROCKEY6
SMART in a grain. For instance, we set IRUT as 0x00000001 and IRUP as 11 11 11 11 11 11 11 11
respectively, and it is recommended for you to use a more complex hexadecimal-string in the practical
application.
ROCKEY6 SMART User Manual V1.3


30

2. When user needs to update software in a remote way, it is necessary for them to provide
hardware-related information to the SW vendor, which including the hardware serial number, current
tag, and current password, except the condition that all of these data had been recorded by SW vendor
already.

Figure52

From the second step of this example, user may obtain all relevant information of his dongle by
using Remote Update Tool, and send these back to the SW vendor by all means; otherwise, SW
vendor may obtain this information relying on the code segment below if it is required to integrate the
remote update feature into those applications of their own.
ROCKEY6 SMART User Manual V1.3


31
unsi gned char Remot ePass[ 8] ;
/ / open t he ROCKEY6 SMART her e
er r code = DI C_Command( hi c, GET_REMOTE_I NFO, cmddat a) ;
Remot eTag = DI C_Get ( cmddat a, REMOTE_TAG, BY_VALUE, NULL) ;
DI C_Get ( cmddat a, REMOTE_PASS, BY_ARRAY, r emot ePass) ;
/ / obt ai n t he har dwar e I D ( HI D) of cur r ent ROCKEY6 SMART
er r code = DI C_Command( hi c, GET_HARDWARE_I NFO, cmddat a) ;
Har dSer i al = DI C_Get ( cmddat a, HARD_SERI AL, BY_VALUE, NULL) ;
m_Har dSer i al . For mat ( " %08X" , Har dSer i al ) ;
/ / f or mat char act er - st r i ng of har dwar e ser i al number
m_Remot eTag. For mat ( " %08X" , Remot eTag) ;
/ / f or mat char act er - st r i ng of r emot e updat e t ag
/ / f or mat char act er - st r i ng of r emot e updat e passwor d
m_Passwor d. For mat ( " %02X %02X %02X %02X %02X %02X %02X %02X" ,
Remot ePass [ 0] , Remot ePass [ 1] , Remot ePass [ 2] , Remot ePass [ 3] ,
Remot ePass [ 4] , Remot ePass [ 5] , Remot ePass [ 6] , Remot ePass [ 7] ) ;
/ / cl ose t he ROCKEY6 SMART

3. SW vendor generated remote update password, one thing should be noted that, if the top digit of
the remote update tag is 1 (the first character greater than 8), represents the user update
password is correlated with the hardware serial number; therefore, all passwords generated will be
unique to each other even with the same user tag altogether. On the other side, the user update
password is independent with the hardware serial number that user input if the top digit is non-1
value of the remote update tag.

4. Received new tag and new password, user may start to process remote update in this way,
and the update tag inside of the ROCKEY6 SMART will be replaced with the new one after update
ROCKEY6 SMART User Manual V1.3


32
successfully. This step can be implemented by using the Remote Update tool provided on SDK, or
you can achieve it in your application with following code segment embedded.
/ / set updat e t ag as t he new one gener at ed by SWvendor ( 0x02)
DI C_Set ( cmddat a, REMOTE_TAG, BY_VALUE, 0x02, NULL) ;
/ / set al l new passwor ds as " 0x22" t o make a smpl e descr i pt i on her e
memset ( Remot ePass, 0x22, 8) ;
DI C_Set ( cmddat a, REMOTE_PASS, BY_ARRAY, 0, Remot ePass) ;
/ / ver i f y r emot e updat e t ag / passwor d
i Ret =DI C_Command( Hi c, CHECK_REMOTE_I NFO, &r I nf o) ;

Following above steps in sequence, SW vendor may succeed in replacing the update tag inside of
ROCKEY6 SMART with the specific one to the user; in addition, if only keeping this example in hand,
preset the cryptographic algorithm inside of dongle and make judgment with method below (code
segment displayed) by internal program are quite feasible for the purpose to achieve the remote update
by SW vendor.
dwor d dwTag;
/ / Obt ai n r emot e updat e t ag
get _r emot e_t ag( &dwTag) ;
i f ( dwTag & 1) ;
/ / Do somet hi ng
esl e i f ( )
/ / Do somet hi ng el se
el se


We believe that all developers have much more knowledge in respect that how to load those
cryptographic algorithms into the ROCKEY6 SMART.
ROCKEY6 SMART User Manual V1.3


33
5.2 Update File
The ROCKEY6 SMART dongle supports Remote Update Management (RUM). The Remote
Module Management (RMM) function will verify the users identity, but it cannot update the external
program because the end user does not have access to the super password, which is required to write
to the dongle.

The SFT process allows the software manufacturer to securely update external programs or data
files without compromising the super password.
The update procedure is as follows:
1. The SW vendor creates a Cipher text file with their ROCKEY6 SMART dongle
2. The manufacturer sends this Cipher text file to their customers
3. The customer transfers the Cipher text file to the dongle with the program provided by the
SW vendor. The dongle will decrypt the Cipher text file and create a Plain text file.

The full process of implementing Update File can be referred to the Figure 5-8.

Supposed that the name of your executable file is 0x1000 and ID is 0x0001, there are three
solutions for you to update file with update file function, in combination with update tag information
described above.

Solution 1: All users are same
Introducing by the feature of Remote update management, if no new password for remote update
was generated after ROCKEY6 SMART plug-in, the Cipher text file created by SW vendor can be
looked as one applied-to-all; in that way, any user belonging to the same SW vendor has no need to
verify the remote update password to finish update operation overall (cannot be verified actually, it is
required to re-plug in the dongle if the password was verified already).
ROCKEY6 SMART User Manual V1.3


34

This solution is quite simple for SW vendor to implement without considering specific process of
remote update, just following such steps as: use IDE to encrypt the executable file with Generate
cipher-text file function, and send this cipher-text file (file output from the function of Generate
cipher-text file) to end-user.

Figure53Generateciphertextfile

While receiving this cipher-text file, the user needs to decrypt it with Generate plain-text file
function, and keep this plain-text file storing inside of the Rocky6 Smart. After that, updated software
can be utilized by user in the normal way; moreover, user can complete the full process of remote
update with the help of Remote Update tool.
ROCKEY6 SMART User Manual V1.3


35

Figure54UserRemoteUpdate

If SW vendor plans to integrate this remote update feature with applications of their own,
understanding the PLAINTEXT_FILE macro is a prerequisite, which was used to generate plain-text
file inside of the ROCKEY6 SMART. Specifically, pass this macro to DIC_Command at first, and make
the memory of plain-text file pointing to the cmddata variable, a plain-text file will be generated inside
of the dongle in this way, see code segment below:
memcpy( cmddat a, c_exef i l e, exesi ze) ;
er r code = DI C_Command( hi c, PLAI NTEXT_FI LE, cmddat a) ;
Note:
c_exefile is the buffer stored cipher-text file, exesize is the size of cipher-text, hic is the handle
ROCKEY6 SMART User Manual V1.3


36
of ROCKEY6 SMART which was opened without super password verification

Solution 2: Part of User is same
During the initialization process of remote update tag and password, set the Initial remote flag
and Initial password as the same value for part of user and make sure the top digit of Initial remote
flag as 0, thus SW vendor may process update respecting a specific set of user, making sure the
update file are same for all of them.

Using this solution, it is necessary to take consistent manufacture-settings respecting Initial
remote flag and Initial password to the same type of Rocky6 Smart in a batch mode; here, we
supposed to set both of two settings as 1 for the simple explanation.

Figure55SetInitialremoteflagandInitialpasswordwhenburninginbatchmode

ROCKEY6 SMART User Manual V1.3


37
After successfully setting Initial remote flag and Initial password, SW vendor can send these
ROCKEY6 SMART dongles to their end user. Following steps are necessary to implement remote
update:
1. Enter a New user flag and Current password against the third step (Acquire update
password) on the main screen of Remote update management, here we take 22222222 as the
New user flag. Clicking the button Acquire update password will generate the Updated
password and appear in the field below, keep information of New user flag and Updated
password in safe place for later use.

Figure56

2. Return back to the main screen of Real device of IDE, click option on menu to generate
Cipher-text file, which involves relevant information about remote update. At such case, SW vendor
ROCKEY6 SMART User Manual V1.3


38
can send their user all of this information, including New remote flag, Updated password, and
Cipher-text file just generated.

3. Received these information, user may update at client-side based on the tool of Remote
Update. Enter the New Tag and New Password on the Update Tag tab screen in first step, and
click Add File button to select specific files to add into the File List show below.

Figure57
The remote update process, at the end, is completed in full-range.

Solution 3: User unique to each other
If setting the top digit of Initial remote flag as 1 during the period of set New IRUP, that is to say,
ROCKEY6 SMART User Manual V1.3


39
the value of Initial remote flag greater than 0x8000000000, the Updated password generated by
remote update is relevant to the hardware serial number of Rocky6 Smart, thus making sure update
files of all user are unique to each other. Comparatively speaking, this solution and Part of User is
same solution are about equal except that the Initial remote flat is set to 1, and more important, SW
vendor have got to provide each user the only update files. Due to the large number of user, SW
vendor could not update user by manually operating tools, but with the help of program running. During
manufacture-initialization, it is approved to apply the Burn real card function of the first solution that all
Initial remote flag and Initial password of ROCKEY6 SMART will be set to the same value, with the
condition that the Initial remote flag had not been used elsewhere.

While updating, SW vendor generate cipher-text file with some basic information obtained by user.
Before writing code, it is a must for SW vendor to understand the CRYPTOTEXT_FILE macro, which
is used by ROCKEY6 SMART to complete the operation of Generate Cipher-text file. The command
buffer required by this macro includes a DISCT_File in the forefront and data of the file next to it. The
macro is used in the same way with the process of generating a file and writing data inside; whereas, it
is a one-pass operation by CRYPTOTEXT_FILE, and store the generated cipher-text file into the
buffer pointed by the variable of cmddata. All important data can be copied from the buffer to a file and
kept in safe mode for later use.

Operation to obtain Initial remote flag:
/ / set " New user f l ag" as 0x02
DI C_Set ( cmddat a, UPGRADE_REMOTE_TAG, BY_VALUE, 0x02, NULL) ;
/ / ent er t he har dwar e ser i al number t o Roceky6 Smar t of r eal user ( supposed
t o be 0x7A85728C)
DI C_Set ( cmddat a, UPGRADE_HARD_SERI AL, BY_VALUE, 0x7A85728C , NULL) ;
memset ( buf f er , 0x02, 8) ;
/ / set al l " New passwor d" as 0x22
ROCKEY6 SMART User Manual V1.3


40
DI C_Set ( cmddat a, UPGRADE_REMOTE_PASS, BY_ARRAY, 0, buf f er ) ;
er r code = DI C_Command( hi c, GET_UPGRADE_REMOTE_PASS, cmddat a) ;
/ / put l at est " Updat ed passwor d" i nt o t he " Remot ePass"
memcpy( Remot ePass, cmddat a, 8) ;
DI C_Set ( cmddat a, FI LL, 512, 0, NULL) ;
/ / cl ear al l
DI C_Set ( cmddat a, FI LE_I D, BY_VALUE, 0x0001, NULL) ;
/ / f i l e I D
DI C_Set ( cmddat a, FI LE_CLASS, BY_VALUE, 0xf f , NULL) ;
/ / f i l e t ype
/ / f i l e pr oper t i es
DI C_Set ( cmddat a, FI LE_ATTRI BUTE, BY_VALUE, FI LEATTR_EXEC, NULL) ;
/ / f i l e si ze
DI C_Set ( cmddat a, FI LE_SI ZE, BY_VALUE, READDATA_SI ZE, NULL) ;
/ / name of execut abl e f i l e 1000
DI C_Set ( cmddat a, FI LE_NAME, BY_ARRAY, 0, " 1000" ) ;
DI C_Set ( cmddat a, FI LE_DATA, BY_ARRAY | READDATA_SI ZE, 0,
( char *) g_pr ogReadDat a) ;
/ / f i l e cont ent
/ / gener at e pl ai n- t ext f i l e
er r code = DI C_Command( hi c, CRYPTOTEXT_FI LE, cmddat a) ;
exesi ze = DI C_Get ( cmddat a, FI LE_DATA, BY_ARRAY, c_exef i l e) ;
Note:
Bothe cmddata and buffer are buffer with enough space, RemotePass is an 8-byte
array, c_exefile is used to store the returned cipher-text file, hic is a handle opened with super
password verification, and READDATA_SIZE is the size of plain-text file.

ROCKEY6 SMART User Manual V1.3


41
Following code segment can be used by SW vendor, in programs running on the client-side:
/ / set " updat e t ag" as t he same val ue wi t h t he new " I ni t i al r emot e f l ag"
gener at ed by SWvendor ( 0x02)
DI C_Set ( cmddat a, REMOTE_TAG, BY_VALUE, 0x02, NULL) ;
/ / set al l of " new passwor d" as " 0x02" f or si mpl y descr i pt i on
memset ( Remot ePass, 0x22, 8) ;
DI C_Set ( cmddat a, REMOTE_PASS, BY_ARRAY, 0, Remot ePass) ;
/ / ver i f y " New f l ag" and " New Passwor d"
i Ret =DI C_Command( Hi c, CHECK_REMOTE_I NFO, &r I nf o) ;
memcpy( cmddat a, c_exef i l e, exesi ze) ;
er r code = DI C_Command( hi c, PLAI NTEXT_FI LE, cmddat a) ;
Note:
cmddata is a buffer with enough space, RemotePass is an 8-byte arrary, c_exefile is the buffer with
cipher-text file storing inside, exesize is the size of cipher-text file, hic is the handle of opened
ROCKEY6 SMART

A point should be taken in consideration respecting above three solutions, the operation of secure
file transfer and remote update tag is operating concurrently if solution 2 and solution 3 were applied.
Further speaking, SW vendor set the New tag and New password to their ROCKEY6 SMART based
on the dongle-related information from the client-side; with this New password at hand and Updated
password saved already, process Generate Cipher-text file and send user above three files
altogether; after that, user may generate plain-text file on the condition that the New tag and New
password had been verified successfully. Mind out the SW vendors operations of obtaining new
password and generating cipher-text file are in the same time, dongle plugging-out or re-opening is
forbidden in the midcourse; in the same manner, the verification of new password and new tag on
client-side are one-step operation, or all correlations between generated cipher-text file and remote
update information are of no effect, like the solution 1 described before.
ROCKEY6 SMART User Manual V1.3


42
SWVendor EndUser
Set Initial remote
flag and Initial
password
Release S/W and
Dongle together
Waif for User Remote
Update
Relative to the
Remote Update
Password?
Generate Cipher-text
files
Obtain New
password
Send user all data
for remote update
Get information of
Hardware ID, Current
flag, and Password
Send SW vendor above
information of individual
Rockey6 Smart dongle
Acquire remote update
information sent by SW
vendor (such as cipher-text
file etc)
Relative to the
Remote Update
Password?
Generate plain-text
files
Verify New flag and
New password of remote
update
Use dongle in a
right way
Y
N
N
Y

Figure58
5.3 Remote Module Manager
Remote module manager includes three parts: setting module definition file, creating module
authority file and setting dongle information module in bulk. For the ROCKEY6 SMART SW vendor, to
manage the remote module requires two steps: firstly, define a module definition file using the module
ROCKEY6 SMART User Manual V1.3


43
definition function; then sent it to the user. The users convert the module definition file to the module
request file according to the actual module they purchased. Secondly, the SW vendor generates the
module authorization file from the users module request file, and sends it back to the user again. As
soon as it was received, user my start to update the ROCKEY6 SMART without delay based on the
module authorization file. If SW vendor make clear of the required module files for each user, the first
step can be completed all by SW vendor alone, that is, sending user the required module files is the
only step for SW vendor to operate in a direct way. Remote Module Management comes down to four
steps listed in below:
By using Integrated Development Environment of ROCKEY6 SMART (IDE), SW vendor defines
the module files (.mod), including all executable files contained in the module and Open/Close status,
and sends this file to the end-user.
By using Remote Update tool of client-side, user generates module required files (.mrq) with
specific requirement definitions, and sends it back to the SW vendor.
With the help of IDE, SW vendor generates module authorization file (.auh) based on the module
required files of particular user, and again sends it to the end-user.
Aiding by Remote Update tool, user selects download authorization and begins updating. The
Open/Close status inside of the ROCKEY6 SMART can be controlled after update with success.
Note:
Module Update needs to be used in conjunction with Remote Update Tag. All of above description
can be implemented with APIs provided by ROCKEY6 SMART.
Module Definition
Choose and fill Module definition from operation types, and add it to the file path via a browser.
Then click the Add button. A module window will pop up. Input the module name for Module, and
choose the dongle file. Click OK to add the module. Once back to the Remote module management
window, click the Add button to add more modules. If more files need to be added into a module, all
ROCKEY6 SMART User Manual V1.3


44
then that is required is to input the same file names into the Add Module message box. Once the
module is added, click the Open/Close button to modify the state of the module. Finally click
Generate file to create the module definition file.

Figure59Addingamodule

Figure510Remotemodulemanagement

ROCKEY6 SMART User Manual V1.3


45
Module Authorization
To generate an authorization file, the developer can convert it simply according to the received
user request file. That is, choose Module authorization from Operation Class, then browse the files
and add the user request file. After that, all user requests are listed. The developer can open and/or
close any modules as required. Click Generate file to finish the module authorization procedure. The
last thing is to send the generated file to the user for updating.

Figure511Remoteauthorizationmanagement

ROCKEY6 SMART User Manual V1.3


46
5.4 Instruction of Remote Update on Client-side
The Remote Update Tools on client-side mainly involve three parts, which are Remote Update, I.e.
remote updating tag for user; Remote File Update, i.e., updating token-inside files of end-user in virtue
of the method of secure file transfer; and Module Management feature, which need to cooperate with
the first section and proceed only after the verification of remote update password. Under \Tools folder
of the Install SDK you may find this Remote Update Tool (RemoteUpdate.exe), all above features will
be implemented through the invocation of API functions; more important, software developers could
encrypt it to their customized tools according to their respective requirements.
Remote Tag Update
Two steps are necessary for user to handle remote tag update; first of all, user need to inform the
manufacturer the data within the field of "Card Information", new tag and password, therefore, will be
created based on these information by manufacturers; and next step, user receive these new logo and
password and enter into the two fields below the "Remote Update" title, and click the "Update" button
on the left panel to start update. Note, if module management is required for this update operation,
please do not click "update" button until the module update is completed, and remote tag will update
immediately after this.
Remote File Update
While it is necessary to handle update, manufacturer will send user some update-need files by way
of secure file transfer. What user needs to do is just use the "Remote File Update" feature of this tool to
add files in turn into the "Update File list", and click "Update" button on the left panel to start update.
ROCKEY6 SMART User Manual V1.3


47
Module Management
Define Requirement
Clicking "Browse" button to select a module definition file, then choose the specified item and
handle "Close/Open" operation based on the file ID List. In the end, click "Generate File" button to
generate a module requirement, which can be sent to the manufacturer by the user.
Download Authorization
Manufacturer generated authorized file based on the module requirement authorization and
subsequently send it to user to begin updating. It is requisite to enter the new update tag and password
into the field of "Remote Update Tag" before downloading authorization, and turn to "Module Manager"
to handle module update without verification of update tag and password. Selecting "Download
Authorization" radio button and browsing files, choose necessary "module authorization files" and click
"update" button on the left panel to start update.







ROCKEY6 SMART User Manual V1.3


48

Chapter 6 Production Management
Once you set up the C51 program, you can burn dongles in bulk. The steps are shown below:
Open ROCKEY6 SMART IDE, as shown in Figure 6-1.

Figure61ROCKEY6SMARTIDE

Click the File | Open Virtual Device menu; then select the intended virtual card file (*.vcr) from the
pop-up window and open it, as shown in Figure 6-2:
ROCKEY6 SMART User Manual V1.3


49

Figure62Virtualdevicewindow

After choosing the executable file, right click your mouse, a menu will pop up as shown in Figure
6-3. Click Burn, the executable file is selected as in Figure 6-4, and its icon is changed. When an
executable file is selected to Burn, it can be downloaded to the real card via the Burn real card
function from the IDE. Otherwise, the executable file never downloads to the real card without selecting
Burn.
ROCKEY6 SMART User Manual V1.3


50

Figure63Choosetheprogramtoburn

The last step is to burn the selected program to the real card. Choose card.vcr, and right click
your mouse. A menu will pop up as in Figure 6-4. Click Burn to real card, then a Burn in bulk window
will be shown.
ROCKEY6 SMART User Manual V1.3


51

Figure64Burntotherealcard

Burn in bulk
The Burn in bulk window contains Volume, Manufacturer information and Remote update
information. Volume is the name of the file system root directory in the dongle. Manufacturer
information holds all relevant information about the manufacturer. Remote update information can be
left without setting until the user really needs it. For details of remote update, please go to section 5.1 -
Remote update management
ROCKEY6 SMART User Manual V1.3


52

Figure65Burninbulkwindow

When the real card is burnt, ROCKEY6 SMART can choose to download some library files as in
Figure 6-5.

Once the burning process is finished, all ROCKEY6 SMART project information will be recorded
into the card.bfl file. The user does not need to repeat the whole setting in the next burning process.
The card.vcr and card.bfl can be transferred to anybody who is going to burn a real card. All that is
required is to follow the steps as in Figure 6-4.

If a program contains a numbers of projects, and every project is allocated with a file ID and file
name, several virtual devices should first be opened as in project (Figure 6-6). After that, copy all the
executable files from every virtual device to one virtual device (Figure 6-7). Finally, give the virtual
device with all setup executable files and card.bfl to the person who will do the burning process.
ROCKEY6 SMART User Manual V1.3


53

Figure66Openmultiplevirtualdevicesinthesameproject

Figure67Copytheexecutablefilestoavirtualcard
ROCKEY6 SMART User Manual V1.3


54


PART 2 Application Section
After finishing this chapter you will know how to use Keil u Vision2 to compile the kernel of your
encryption application and choose the corresponding API function, and you will also learn the
development procedure of ROCKEY6 SMART.

Chapter7,DebugwithROCKEY6SMARTSimulator
This chapter will describe how to configure the development environment of Keil u Version2.After
finishing this chapter the user will grasp some fundamental debugging procedures of Rocket6 SMART.

Chapter8,Rocket6SMARTEssential
This chapter will show how to encrypt a program step by step from a simple sample. You will learn
how ROCKEY6 SMART protects your applications.

Chapter9,APIReferenceofCommunicationwithROCKEY6SMART
The user will learn how to use the API from this chapter.

Chapter10,APIReference
This chapter is the continuation of the last. The user will learn more details of the API from a
sample.





ROCKEY6 SMART User Manual V1.3


55

Chapter 7 DEBUG WITH ROCKEY6 SMART
SIMULATOR
ROCKEY6 SMART Simulator is used for simulating all hardware functions for ROCKEY6 SMART.
The user does not actually need the hardware to perform the real card functions, as well as software
debugging and execution. Please note: ROCKEY6 SMART Simulator is based on the Keil uVision2
debugger. Therefore, it can only work for code that is compliant with the Keil environment. If users do
not need to debug the C51 program, it is not necessary to configure the simulator as well.
7.1 Configure Keil IDE
Before using Keil to develop ROCKEY6 SMART, some projects need to be set. Firstly,
copy \TOOLS\Debugger\RySSimulator.dll from the ROCKEY6 SMART installation folder
to Keil\C51\BIN and also copy \API32\Dynamic\dic32u.dll to keil\UV2, or copy DIC32U.dll to the
system folder. After that modifyTOOLS.INI and append TDRV4=BIN\RySSimulator.dll (FEITIAN
RockeySmart Simulator) at the end of the C51 block. TDRV4 is the serial number and it can use
the next number to replace the number when it is occupied.
7.2 Create a project
To create a new project, open Project of KEIL UV2 and click New Project. Input the project
name in the pop-up dialog box and save it.

Choose 51 serial CPU when Options for Target Target1 appears. Users need to re-choose CPU
ROCKEY6 SMART User Manual V1.3


56
for the existing project without 51 serial CPU.

Figure71
7.3 Project Configuration
Click Project >Options for Target Target1 to get high efficiency, use default setting (small model)
in Target menu as shown in Figure 7-2
ROCKEY6 SMART User Manual V1.3


57

Figure72

In Figure 7-2 Project---Options for Target Target1 page, tick Create HEX File and Run User
Program #1 and type hexbin.exe test.hex test.bin in the text box. Additionally the name of test.hex
and test.bin will be changed according to the name of the project. Before using it, copy
\TOOLS\Debugger\hexbin.exe to the project folder. Please note, it is not necessary that you use this
option only for debugging your application; however it is necessary that your application is ready for
bulk burning to ROCKEY6 SMART by writing extended code using third party tools, because the BIN
file is an executable file in the ROCKEY6 SMART.
ROCKEY6 SMART User Manual V1.3


58

Figure73

Select the simulator in the debug page and tick Go till main. When programming the ROCKEY6
SMART and debugging the program is required, the software developer has to tick Go till main. That
is for jumping over the initial code and jumping into the main function. Shown in Figure 7-4
ROCKEY6 SMART User Manual V1.3


59

Figure74

After this, clicking setting to configure the FEITIAN ROCKEY6 SMART simulator. If you connect
the real card then select the Using real card option. Whether choosing this option or not is dependant
on whether the user downloads the program into the real card to debug the program. Otherwise, the
user does not need configure this option and also can even debug the program without a real card as
shown in Figure 7-5:
ROCKEY6 SMART User Manual V1.3


60

Figure75

Eventually, configure the debugger for downloading. There will appear an icon in the main
frame, which can be used for burning the program to the real card after the user debugs it. No matter if
burning to a real card or a virtual card, the aim of burning to a virtual card is getting ready for the bulk
burn. Details are shown in Figure 7-6.
ROCKEY6 SMART User Manual V1.3


61

Figure76

Add source file into project
View >Project window spread the tree and right click source Group1; select Add files to
Group source Group1 to add the corresponding head file and library file in API\C51 into the project.
Shown in Figure 7-7:
ROCKEY6 SMART User Manual V1.3


62

Figure77

When debugging the program, RySSimulator.dll simulates the ROCKEY6 SMART and explains
and performs functionality as per the dongle. Therefore the user does not really need a card to perform
an operation on an executable file.

After addingAPI32\C51\sys_api.h andsmall_mode.LIB into the project, the user can debug and
burn the card. The user does not need to configure the output file. Output is controlled by Keil IDE and
the debugger.
7.4 Debugging
After performing the above configuration steps, the program will be in the debugging state. At this
ROCKEY6 SMART User Manual V1.3


63
point, the Keil uVision2s simulator can be used to debug (choose Use Simulator button from the
upper left part of Figure 2-3). However, there is one difference. - the register shows in menu View >
Project Window the VM51 register rather than the register of Keil uVision2 Simulator register. For
details of using and debugging Keil uVision2, please refer to its user manual.

7.5 Quit
To end the debugging process, exit() has to be used at end of the debugging program.
ROCKEY6 SMART Simulator will end once it executes exit (). It is the same as the user choosing the
Debug >Start/Stop Debug Session menu. In other words, if the user chooses the Debug >Start/Stop
Debug Session menu, the debugging process can be ended at any stage. If the PC pointer refers to
address 0, the process will be restarted.

7.6 Sample Debugging
ROCKEY6 SMART Simulator will debug and test all examples under the directory \samples\keil\.
The results are exactly the same as the descriptions in the readme.txt file.
NOTE: The simulator cannot simulate the function sys_recall, because this function is meaningless in
the simulator. In addition, please do not use any other methods to generate the BIN file into the card
for execution. If you want to input the code into the card for execution, please choose Download from
the menu Flash, or you can click the tools bar Download to Flash Memory button.

ROCKEY6 SMART User Manual V1.3


64
7.7 Write Program to the real card
If the Using Target Driver for Flash Programming in the Utilities page is set, the program is ready
to write into the real card. The only thing that needs to be done is to select Flash >Download from
Keil. After that, the whole procedure is finished.

7.8 Summary
In all, ROCKEY6 SMART Simulator not only controls all compilation and execution of the VM51,
but also provides all ROCKEY6 SMART services, such as various file operations, choosing files,
reading, writing, creating, float type calculations, and card information operations etc. With these
advantages, VM51 developers can easily use the simulator to debug VM51 programs.




ROCKEY6 SMART User Manual V1.3


65

Chapter 8 ROCKEY6 SMART Essential
8.1 Development Introduction
ROCKEY6 SMART is a programmable dongle, it has two development models: one is dongle
internal program; another is the external program that communicates with the program inside the
dongle. After the dongle software and hardware are setup, please follow the steps below to develop a
simple protection program.
8.2 Fundamental Usages
ROCKEY6 SMART dongle is developed by using C language. Developers need to study the
provided system functions usages before they deploy the dongle.
The following diagram represents the process for dongle configuration:


Figure81DevelopmentProcess

Please consider the following algorithm: Input 15 bytes ID numbers, its output is 18 bytes numbers.
This is a simple message-digest algorithm. Assume these numbers are a part of critical code, and then
ROCKEY6 SMART User Manual V1.3


66
we save these numbers into the dongle. An example is as follows:
1 unsi gned char Wi [ 18] = {7, 9, 10, 5, 8, 4, 2, 1, 6, 3, 7, 9, 10, 5, 8, 4, 2, 1};
2 char Ai [ 11] ={1, 0, x, 9, 8, 7, 6, 5, 4, 3, 2};
3 voi d Conver t I D( char I D[ 15] , char newI D[ 18] )
4 {
5 i nt i , j , s;
6 s=0;
7 memcpy( newI D, I D, 6) ;
8 newI D[ 6] =1;
9 newI D[ 7] =9;
10 memcpy( newI D+8, I D+6, 9) ;
11 f or ( i =0; i <17; i ++)
12 {
13 j =( newI D[ i ] - 48) *Wi [ i ] ;
14 s+=j ;
15 }
16 s%=11;
17 newI D[ 17] =Ai [ s] ;
18 }

Following is an example written in C51 C language. It will do the same thing.
unsi gned char Wi [ 18] = {7, 9, 10, 5, 8, 4, 2, 1, 6, 3, 7, 9, 10, 5, 8, 4, 2, 1};
char Ai [ 11] ={1, 0, x, 9, 8, 7, 6, 5, 4, 3, 2};
voi d mai n( voi d)
{
i nt i , j , s;
ROCKEY6 SMART User Manual V1.3


67
s=0;
byt e I D[ 15] , newI D[ 18] ;
get _i nput ( I D, 0, 0, 15) ; / / I nput I D number s
memcpy( newI D, I D, 6) ;
newI D[ 6] =1;
newI D[ 7] =9;
memcpy( newI D+8, I D+6, 9) ;
f or ( i =0; i <17; i ++)
{
j =( newI D[ i ] - 48) *Wi [ i ] ;
s+=j ;
}
s%=11;
newI D[ 17] =Ai [ s] ;
set _r esponse( newI D, 18) ; / / Out put new I D number s
exi t ( ) ; / / pr ogr amends
}


The 3rd line is the main function definition. The 8th line: get_input(ID,0,0,15) is used for receiving
the external input data. ID is buffer, parameter 2 means offset, 3 means the input data type, 0 means
byte and 15 means data length. The 20th line:set_response(newID, 18) returns the data to the host
machine. In this function, newID refers to the buffer address, 18 means the length of the output data.
exit() means program ending.

In the KEIL compile environment, C language id used. However, it is different to standard C
language due to its distinguished methods for defining variables. An example is: unsigned char xdata
ROCKEY6 SMART User Manual V1.3


68
buf[128]. xdata means putting the variable into the xdata area. If a lager array is defined, it is
usually assigned at the xdata area in order to obtain enough memory space. Please refer to the C51
user manual for further details and features of C51.
8.3 Creating C51 Project
To convert the core code into KEIL C language, again create a C51 project. This part of the core
code can be compiled, debugged and downloaded to the dongle.

After creating a C51 project, please add your source code, SDK files: API32\C51\Small_Mode.lib
andsys_api.h into the project.

Once this step is completed, you can start to debug, compile and/or download your program.

8.4 Creating an Executable File in the Dongle
Once the project is created, the source code can be compiled and debugged. It can be debugged
using different methods, such as in steps or in blocks. See Figure 8-2:

ROCKEY6 SMART User Manual V1.3


69

Figure82DebuggingWindow

If the debugger meets the function get_input and/or set_response, it will display the following
window for data input or data content display. (The example will use getversion function).The
difference from running the card is when the debugger meets more get_input functions, it will display
more dialog boxes for user input. In debugging, the user can ignore this parameter. As shown in Figure
8-3.

Figure83OutputData
ROCKEY6 SMART User Manual V1.3


70
Once the code is successfully compiled, it can be downloaded to the card by using the discussed
method in the previous section. Now, if you open the IDE tool to browse real devices, you will find a file
with its name and ID being 2000. When the file is executed, it can dynamically fetch the files it needs,
and return the corresponding results. As shown in Figure 8-4, Figure 8-5.

Figure84FilesInTheRealCard

Figure85SimulatedExecutions

Now, click the Browse Real Device button from the tool bar, then you can find the file. Once you
have finished all previous steps, a communication module needs to be created for communicating to
the card.
ROCKEY6 SMART User Manual V1.3


71
8.5 Editing and Encrypting Dongle Intercommunication Program
The steps for executing a dongle file:

Figure86FileExecutionSteps

Following is a configured API that is used for communications between application programs and
the ROCKEY6 SMART dongle:
EXTERN_C i nt WI NAPI DI C_Fi nd( DWORD UI D) ;

The function is used for dongles attached to the PC, based on the user code, and returns the total
numbers of attached dongle devices.
EXTERN_C i nt WI NAPI DI C_Open( i nt hi c, char * r eader _name) ;

Open a dongle from its index, and return the handle of the dongle
EXTERN_C i nt WI NAPI DI C_Command( i nt hi c, i nt cmd, voi d* cmddat a) ;

Sends commands to the dongle. The first parameter is the handle of the dongle; the second
parameter is command macro; the third parameter is the inputting/outputting structures for command
macroDIC_Set andDIC_Get are described in detail at <<User Manual>>. Please note that these two
functions are not used for any dongle operations. They are simply used to set a buffer. The address of
the buffer can be transferred to the 3rd parameter of the functionDIC_Command This buffer is the
required structure. For all structures supported C languages, it is not necessary to use these two
functions. According to the definition of the functionDIC_Command, these languages can directly
work on the various structures based on different macros. The purpose of these two functions is to help
ROCKEY6 SMART User Manual V1.3


72
users to configure complicated data structures; especially for those languages which do not
supportstruct, such as VB etc.

Here is an example of converting the ConvertID to the function that can communicate with the
dongle:
1 voi d Conver t I D( const char I D[ 15] , char newI D[ 18] )
2 {
3 DI CST_Bef or e_Run_Dat a *bD=( DI CST_Bef or e_Run_Dat a *) new char [ 48] ;
4 DI CST_Af t er _Run_Dat a *aD=( DI CST_Af t er _Run_Dat a *) bD;
5 i nt count =DI C_Fi nd( ) ; / / Sear ch dongl e
6 i nt hi c=0;
7 f or ( i nt i =0; i <count ; i ++)
8 {
9 i f ( ( hi c=DI C_Open( i , NULL) ) >=0)
10 br eak;
11 }
12 i f ( hi c==count )
13 r et ur n; / / Dongl e i s not f ound
14 bD- >RunI D=0x2000; / / Set t he execut abl e f i l e name
15 bD- >Par aSi ze=15; / / I nput t he l engt h of buf f er
16 memcpy( bD- >Par a, I D, 15) ; / / I nput buf f er
17 i nt r et =DI C_Command( hi c, RUN, bD) ; / / Run t he f i l e and wai t f or t he
r et ur n dat a
18 memcpy( newI D, aD- >Resul t , aD- >Resul t Si ze) ; / / Get r et ur n dat a
19 }

Now, the entire project protection work is done. The newly formed interface is the same as the
ROCKEY6 SMART User Manual V1.3


73
previous one, and it does not need to be modified for execution.
8.6 Core Code Selection
From the above example, we have introduced a fundamental software encryption protection
method. This example is quite simple and used for describing the idea only. Please do not use it directly
in your protection. Based on our experience, many users are using dongles for only searching if they
are attached to the PC, or only storing a piece of dispensable code inside the dongle. Dongles used in
this way cannot protect your software well. We recommend users take more time to configure their
dongles. Following are some important principles and methods used for dongle applications.

Code inside the dongle has to be vital. This part of code has to be saved inside the dongle.
Nobody can get to it without undergoing the valid verification procedures and the main program
cannot be executed entirely and successfully without this vital part of code. As a result, if hackers
attempt to avoid this piece of code the whole program cannot be executed successfully.

Try to choose the specific code that relates to your application. Since popular algorithms are well
known, software hackers can generally guess the functionalities of the code and simulate them to
crack the software. Based on the fact that most of our clients are skilled software programmers in their
own software applications, we recommend our clients to add their own special code in the dongle. It is
impossible for a hacker to know all the code from various application fields and the dongle containing
the special code would be too hard to be broken for a hacker. For example, a graphics programmer
could use part of the code from the graphic processing software in the dongle; a PC games
programmer could use part of the code from the artificial intelligence algorithms; a mechanical
engineer could use part of the code from the mechanics algorithms etc. In this way, the dongles would
have dynamic diversity for its security algorithm applications and would make cracking the software
too difficult to accomplish.
ROCKEY6 SMART User Manual V1.3


74

From the performance aspect, do not give a heavy workload to the dongle. The code inside the
dongle can be executed within the dongle. Since the speed of the dongle microprocessor is slower
than the PC CPU, the dongle usually creates a bottleneck for the entire computation. Therefore, do
not input the dongle code to an executing game, ONMOUSEMOVE of the interface program etc.
Please try to use this piece of code safely. Once it is correctly used, even with some complex
computation, the whole system may be slower but wont be crashed.
8.7 Summary
From the above, we have discussed the fundamental methods for using the software protection
dongle. Moreover, we have also shown how to separate and convert the code into C language. Finally,
we have described how to arrange the main program and communication modules of the smart card,
as well as how to choose core code in the dongle.

Again, please take more time for programming your dongle software. It is crucial for protecting your
software.
ROCKEY6 SMART User Manual V1.3


75

Chapter 9 ROCKEY6 SMART Communication
API Reference
9.1 int DIC_Find()
Category Description
Function Find dongle devices connected to the PC
Input No
Return value If return value is less than 0, then it means the return value is incorrect.
Please refer to Appendix E for details.
If returned value is 0, it means there is no connected device found.
If the returned value is greater than 0, then the returned value is the
actual numbers of devices. (NOTE: In most cases, although there are no
external devices attached, because device driver is installed in the PC;
then it looks to see if the external device exists. To ensure this, it is
necessary to use command DIC_Open to check if it is true.)
Theoretically, the maximum external connected card readers are 32.
Usage
Description
In most cases, this command is only used once when the program is
initiated by the user. It can result in some initiation work, such as listing
all internal card readers. If the user is using concurrent multi programs,
then it is only the main program that needs to call this command once.
If the user plugs physically in/out the external card dongle, it will not
cause any number changes for the displayed card dongle.

ROCKEY6 SMART User Manual V1.3


76
9.2 int DIC_FindByMgrCode(void * pMgrCode)
Category Description
Function Search encryption devices connected to the computer
Input Manufacturer management code
<0 :Error ,Refer to the error code
=0 :No device
Return value
>0 :Return the number of connected dongles
Usage
Description
Normally, this command is used for initializing the dongle and creating
the dongle list.
We recommend developers invoke this command at the beginning of the
main thread.

9.3 int DIC_Open (int hic, char* reader_name)
Category Description
Function Open selected card reader
ROCKEY6 SMART User Manual V1.3


77
hic (1) Positive value is an enumerate value and is a
number of 0, 1, 2 ... which is in the range of returned
values of DIC_Find(). If reader_name is not empty,
then its return value is the name of the card reader.
(2)Negative values, in this case, the parameter of
reader_name cannot be empty. DIC_Open will try
to directly use the reader name from the
reader_name to open the corresponded card
reader. If the card reader is a virtual device, then it is
the path of the file.
Input
reader_name It is a parameter of input/output, please see also hic
description
>=0 Represents success. The returned value is the
opened handler.
Return value
<0 The return value is an error code; please refer to
Appendix E for details.
Usage
Description
It results in establishing the unique connection to the connected device.
Once the operations are finished, the user should release the resources
held by the connection via command DIC_Close. It is more important
for using concurrently multi programs.
9.4 int DIC_Close(int hic)
Category Description
Function Close selected card reader
Input Card handler, it will be ok if it is the same as the DIC_Open returned
ROCKEY6 SMART User Manual V1.3


78
hic.
Return The return value is an error code; please refer to Appendix E for details.
Usage
Description
It is used for releasing the connection between the PC and external
devices. At the same time, clear the data and security state in the device
memory.

9.5 int DIC_Command(int hic, int cmd, void* data)
Category Description
Function Finish the operation for selected device
hic Device handle
cmd Specific operation; it usually uses various constants to
represent different operations. Please also see [cmd
Description] for details.
Input
data All command related input/output data, please also see
[special data structure] description
Return The return value is an error code; please refer to Appendix E for details.
Usage
Description
It is a multi-functional command, all devices related to this operation are
accomplished by this command

[cmdDescription]
Every command constant is already defined as a macro in Dic32u.h, referring to different
operations. Some of the macros may conflict with macros predefined under various integrated
development environments, and pre-compiling will not report such conflicts. If the syntax convention is
correct but cannot perform the corresponding functions, please take the relevant constants in
ROCKEY6 SMART User Manual V1.3


79
Dic32u.h as parameters or rename the related macros before they are used. Normally, there is no
need to care about the related data structures, use mode operation to get and set the data structures.
Detailed descriptions are available under Dic_Det() and Dic_Set().
Macro Data Structure Operations
GET_CARD_INFO DICST_CardInfo Get smart card volume
and manufacturer
information
GET_HARDWARE_INFO DICST_HardInfo Get hardware
manufacture date, serial
number, shipping time
and COS version
GET_MANAGER_CODE DICST_ManagerCode Get management code;
include zone code,
reseller code and two
users codes.
GET_CARD_PRIVILEGE 1 byte Get card current
password verification
state. There are 3
returned values:
0(password not verified),
4(super password
verified), 8(remote
update password verified)
GET_REMOTE_INFO DICST_RemoteInfo Get remote update
information
SET_REMOTE_INFO DICST_RemoteInfo Setup remote update
information
ROCKEY6 SMART User Manual V1.3


80
CHECK_REMOTE_INFO DICST_RemoteInfo Verify remote update
information
GET_CURRENT_DIR DICST_Dir Get current directory
information
SET_CURRENT_DIR DICST_Dir Setup current directory
information
GET_CURRENT_FILE DICST_File Get current file
information
SET_CURRENT_FILE DICST_File Setup current file
information
GET_PARENT_DIR DICST_Dir Get upper directory
SET_PARENT_DIR DICST_Dir Setup upper directory
LIST_DIR Input 1byte index, specifying
the file to be opened, index:
0-255. DICST_Dir or
DICST_File
List directory structure of
file system; it is
determined by the
FILEATTR_DIR from the
returned data.
READ_FILE DICST_Before_Read_Data
and
DICST_After_Read_Data
Read current file (first
read file information, then
its content)
WRITE_FILE DICST_Write_Data Write a file into the card
FORMAT_CARD DICST_System_Info Format the card
CREATE_DIR DICST_Dir Create a directory
CREATE_FILE DICST_File Create a file
REMOVE_DIR DICST_Dir Delete a directory
REMOVE_FILE DICST_File Delete a file
ROCKEY6 SMART User Manual V1.3


81
RANDOM char array Get a random number
RUN DICST_Before_Read_Data
and DICST_After_Run_Data
Run an executable file
CRYPTOTEXT_FILE none Encrypt a file
PLAINTEXT_FILE none Decrypt a file
CHECK_SUPER_PASS char data[] Verify the super password
SET_SUPER_PASS DICST_SuperPass_Data Setup the super password
GET_UPGRADE_REMOTE
_PASS
DICST_Upgrade_RemotePa
ss
Get remote update
information
DESENC DICST_Des_Data and
DICST_After_EncDec_Data
DES encryption
DESDEC DICST_Des_Data and
DICST_After_EncDec_Data
DES decryption
RSAGENKEY DICST_Rsa_GenKey RSA generates key pairs
RSAENC DICST_Rsa_Data and
DICST_After_EncDec_Data
RSA encryption
RSADEC DICST_Rsa_Data and
DICST_After_EncDec_Data
RSA decryption
GETFREESPACE Returned value is a DWORD Get the remaining space
of the file system
SETCOUNTER Inputted value is a DWORD Begin the maximum using
counter
STEPCOUNTER none reduce the using counter
numbers in each step

[SpecialDataStructure]
All operations of data structures can be accomplished with mode operations in DIC_Get and
ROCKEY6 SMART User Manual V1.3


82
DIC_Set. Normally, there is no need to care about these data structures, it is not recommended to use
the structures, because it would reduce their transferability.
============================================================
DI CST_Car dI nf o / *Set by t he sof t war e devel oper */
t ypedef st r uct {
char vol ume[ 16] ; / / Dongl e vol ume
char at r [ 15] ; / / Manuf act ur er i nf or mat i on
} DI CST_Car dI nf o;
===========================================================
DI CST_Har dI nf o
/ *I nf or mat i on set by Fei t i an, sof t war e devel oper i s not aut hor i zed t o modi f y
i t */
t ypedef st r uct {
DWORD Fact or yTi me; / / Manuf act ur e dat e
DWORD Har dSer i al ; / / Ser i al number
DWORD Shi pTi me; / / shi ppi ng t i me
DWORD COSVer si on; / / COS ver si on
} DI CST_Har dI nf o;
===========================================================

DI CST_Manager Code
/ *I nf or mat i on set by Fei t i an, sof t war e devel oper i s not aut hor i zed t o modi f y
i t */
t ypedef st r uct {
WORD Zone; / / Zone code
WORD Agent ; / / Resel l er code
WORD User 1; / / User code 1
ROCKEY6 SMART User Manual V1.3


83
WORD User 2; / / User code 2
} DI CST_Manager Code;
===========================================================
DI CST_Remot eI nf o / *Set and comment ed by t he sof t war e devel oper */
t ypedef st r uct {
DWORD Remot eTag; / / Remot e updat e t ag
BYTE Remot ePass[ 8] ; / / Remot e updat e passwor d
} DI CST_Remot eI nf o;
===========================================================
DI CST_Di r
t ypedef st r uct {
WORD di r i d; / / Di r ect or y I D
BYTE di r cl a; / / Di r ect or y cat egor y
BYTE di r at r pr i ; / / Di r ect or y at t r i but e & di r ect or y secur i t y l evel
WORD di r si ze; / / Not used
char di r name[ 16] ; / / Di r ect or y name
} DI CST_Di r ;
==========================================================

DI CST_Fi l e
t ypedef st r uct {
WORD f i l ei d; / / Fi l e I D
BYTE f i l ecl a; / / Fi l e cl ass
BYTE f i l eat r pr i ; / / Fi l e at t r i but e & f i l e secur i t y l evel
WORD f i l esi ze; / / Fi l e si ze
char f i l ename[ 17] ; / / Fi l e name
} DI CST_Fi l e;
ROCKEY6 SMART User Manual V1.3


84

Definitions of diratrpri(directory attribute) and fileatrpri(file attribute)
Label Type
FILEATTR_NORMAL Normal data file
FILEATTR_EXEC Executable
FILEATTR_DIR Directory
FILEATTR_UPIGNORE If the current security level is already higher than the
executable program, the program cannot be executed.
FILEATTR_INTERNAL File used by internal program and cannot be operated
externally. If an executable file is marked as internal, it
has hiding properties, such files can be viewed when
listing directory only if the super password is verified.



===========================================================
DI CST_Upgr ade_Remot ePass / *Used i n r emot e updat e management */
t ypedef st r uct {
DWORD Remot eTag; / / Remot e updat e t ag
DWORD Har dSer i al ; / / Har dwar e ser i al number
BYTE Remot ePass[ 8] ; / / Remot e updat e passwor d
} DI CST_Upgr ade_Remot ePass;
===========================================================
DI CST_Bef or e_Read_Dat a
t ypedef st r uct {
WORD of f set ;
ROCKEY6 SMART User Manual V1.3


85
WORD si ze;
} DI CST_Bef or e_Read_Dat a;
============================================================
DI CST_Af t er _Read_Dat a
t ypedef st r uct {
WORD r eadedsi ze;
char buf f er [ 1] ; / / The si ze i s r eadsi ze
} DI CST_Af t er _Read_Dat a;
===========================================================
DI CST_Wr i t e_Dat a
t ypedef st r uct {
WORD of f set ; / / Fi l e of f set
WORD si ze; / / Fi l e si ze
char buf f er [ 1] ; / / The si ze i s si ze
} DI CST_Wr i t e_Dat a;
===========================================================
DI CST_Syst em_I nf o / * Set t he dongl e vol ume and vendor i nf or mat i on af t er
f or mat t i ng*/
t ypedef st r uct {
char vol ume[ 16] ; / / Vol ume
char at r [ 15] ; / / Manuf act ur er i nf or mat i on
} DI CST_Syst em_I nf o;
===========================================================
DI CST_Bef or e_Run_Dat a
t ypedef st r uct {
WORD RunI D; / / Fi l e I D
WORD Par aSi ze; / / Par amet er si ze
ROCKEY6 SMART User Manual V1.3


86
BYTE Par a[ 1] ; / / The si ze i s Par aSi ze
} DI CST_Bef or e_Run_Dat a;
===========================================================

DI CST_Af t er _Run_Dat a
t ypedef st r uct {
WORD Resul t Si ze; / / Byt e number of r et ur n par amet er
BYTE Resul t [ 1] ; / / The si ze i s Resul t Si ze
} DI CST_Af t er _Run_Dat a;
===========================================================
DI CST_Super Pass_Dat a
t ypedef st r uct {
BYTE MaxTr yTi mes; / / Maxi mumr et r y number , shoul d not be 0
BYTE Super Pass[ 8] ; / / Super passwor d, can not be al l 0, ot her wi se i t i s l ocked.
} DI CST_Super Pass_Dat a;

9.6 int DIC_Get(void* target, int p1, int p2, char* pstr);
Category Description
Function Get data
target Source data buffer Input
p1 Mode/shift, if the highest bit is 1, then it is a mode operation;
otherwise, it is a user defined shift value
ROCKEY6 SMART User Manual V1.3


87
p2 Return mode / size, the highest 2 bits represent return
mode, others indicate the operation size

pstr Character type buffer where the data is obtained

Return If return mode is BY_VALUE, the return data is the data required by the
user. If it is BY_ARRAY, the returned value is the data length of pstr
buffer. If it is BY_STRING, the returned value is the character string
length of pstr buffer.
Note: For some model operations like vendor information, no matter
what return mode is set, it will return from pstr. Then if pstr is set to
NULL, the return of -1 indicates that the required operations can not be
performed

Usage
Description
The data pointer in DIC_Command can be regarded as a structure
pointer in C. But for many languages that do not support structure,
DIC_Get and DIC_Set are for storing to / getting from the structure

[p1description]
For the p1 parameter of DIC_Get and DIC_Set, some macros are defined to specify the operation
objects. The highest bit of the macros is set to 1. The following are the pre-defined macros:
Macro Description
FILL Fill
ATR Manufacturer information
ROCKEY6 SMART User Manual V1.3


88
VOLUME Volume
FACTORY_TIME Manufacture date
HARD_SERIAL Hardware serial number
SHIP_TIME Shipping time
COS_VERSION COS version
ZONE Zone code
AGENT Reseller code
USER1 User code 1
USER2 User code 2
DIR_ID Directory ID
DIR_CLASS Directory category
DIR_ATTRIBUTE Directory attribute
DIR_PRIVILEGE Directory privilege status
FILE_NO File number
DIR_NAME Directory name
FILE_ID File ID
FILE_CLASS File category
FILE_ATTRIBUTE File attribute
FILE_PRIVILEGE File security level
FILE_SIZE File size
FILE_NAME File name
WRITE_DATA Write data
READ_DATA Read data
RUN_DATA Runtime input/output data
RANDOM_SIZE Random number size (in byte)
REMOTE_TAG Remote update tag
ROCKEY6 SMART User Manual V1.3


89
REMOTE_PASS Remote update password
UPGRADE_HARD_SERIAL Hardware serial number
UPGRADE_REMOTE_TAG New remote update tag
UPGRADE_REMOTE_PASS New remote update password
REMOTEPASS_STATUS Remote update status
SUPERPASS_STATUS Super password verification status
SUPERPASS_DATA Super password

[p2Description]
For the p2 parameter of DIC_Get and DIC_Set, the highest 2 bits indicate data transfer or return
mode, the default value of the lower 30-bit is 0, if not, it refers to the operation byte number.
Macro Description
BY_VALUE Value transfer
BY_ARRAY Array transfer
BY_STRING In term of character

[Example]
/ / I f t he hi ghest bi t of p1 i s not 1, t hen t he f unct i on i s t o get t he user
dat a.
char t st r [ ] = " Hel l o Wor l d! " ;
char pst r [ 20] ;
DI C_Get ( t st r , 3, BY_ARRAY | 5, pst r ) ;
Then, the content of pstr is "lo Wo", 3 is the shift value, and 5 is the size.
ROCKEY6 SMART User Manual V1.3


90
9.7 int DIC_Set(void* target, int p1, int p2, int p3, char* pstr)
Category Description
Function Data setup
target Target buffer zone
p1 Mode/shift, if the highest bit is 1, it is a mode operation,
otherwise, it is user defined shift value
p2 Transfer mode/ size, the highest 2 bits specify the transfer
mode, others indicate the operation size
p3 Normally, it is the user value to be stored
Input
pstr Character type buffer of the source data, it can be NULL
Return 0 means success, otherwise is 1.

[Example]
DI C_Set ( dat a, FI LL, 256, 0, NULL) ;
/ / Cl ear t he 256- byt e dat a
DI C_Set ( dat a, FI LE_I D, BY_VALUE, 0x2100, NULL) ;
/ / Set t he f i l e I D i n t he dat a
DI C_Set ( dat a, RUN_I D, BY_VALUE, 0xA1B2, NULL) ;
/ / Set t he f i l e I D t o be execut ed i n t he dat a
9.8 int DIC_GetVersion(char* ver)
Category Description
Function Get the dynamic library version
ROCKEY6 SMART User Manual V1.3


91
Input ver is used to return the version number of the dynamic library.
The content is: [V/R]xx.yy
For example: R01.10 means it is the real card dynamic library version
1.10 Another example:R03.02 means it is virtual card dynamic library
version 3.02.
Return An error code is returned, please see also Appendix E

9.9 Returned Error Code
Code(hex) Code(decimal) Description
0x00000000 0 Correct, no error.
0x80100001 -2146435071 Internal connection check failed
0x80100002 -2146435070 Operation is terminated by the user
0x80100003 -2146435069 Incorrect operation handler
0x80100004 -2146435068 Incorrect parameters
0x80100005 -2146435067 Invalid registering information or the information is lost
0x80100006 -2146435066 No enough memory to accomplish the instruction
0x80100007 -2146435065 Internal overtime
0x80100008 -2146435064 The user defined buffer is too small to hold all returned data
0x80100009 -2146435063 Card reader is unknown
0x8010000A -2146435062 User assigned time exceeds
0x8010000B -2146435061 The card is occupied by the other connection
0x8010000C -2146435060 There is no card in the card reader
0x8010000D -2146435059 Unknown card type
0x8010000E -2146435058 Card reader is unable to quit card operation
ROCKEY6 SMART User Manual V1.3


92
0x8010000F -2146435057 The current card does not support the user defined
communication protocols
0x80100010 -2146435056 Card is not ready for receiving instructions
0x80100011 -2146435055 Some variable values are invalid
0x80100012 -2146435054 Operations are terminated by the system. You may need to
re-logon or restart the machine.
0x80100013 -2146435053 Internal communication error
0x80100014 -2146435052 Unknown internal error
0x80100015 -2146435051 Invalid manufacturer information
0x80100016 -2146435050 User has tried to stop a process that it is not actual existing.
0x80100017 -2146435049 The selected card reader is not available right now.
0x80100018 -2146435048 Operation is stopped; the service programs could have quit.
0x80100019 -2146435047 The receiving buffer of PCI is too small
0x8010001A -2146435046 The driver of card reader does not support current card
reader.
0x8010001B -2146435045 The card reader driver cannot get the unique name, due to a
duplicated name.
0x8010001C -2146435044 Card is not supported by current card reader.
0x8010001D -2146435043 The smart card services do not start.
0x8010001E -2146435042 The smart card services are stopped.
0x8010001F -2146435041 An unexpected card error occurs.
0x80100020 -2146435040 Unable to get providers information of the smart card.
0x80100021 -2146435039 Unable to get manufacturers information of the smart card.
0x80100022 -2146435038 The user requested functions are not supported by current
smart card.
0x80100023 -2146435037 The selected directory does not exist.
ROCKEY6 SMART User Manual V1.3


93
0x80100024 -2146435036 The selected file does not exist.
0x80100025 -2146435035 The selected directory is invalid.
0x80100026 -2146435034 Selected file is invalid. No file has been selected now.
0x80100027 -2146435033 Access denied for current file
0x80100028 -2146435032 The space of card is full. No information could be written in.
0x80100029 -2146435031 Configuration file pointer error
0x8010002A -2146435030 PIN code error
0x8010002B -2146435029 An unidentified error code returned from the smart card
service.
0x8010002C -2146435028 Requested certificate does not exist
0x8010002D -2146435027 The request for getting the certificate is denied.
0x8010002E -2146435026 Cannot find any card reader
0x8010002F -2146435025 Data is lost during the process of the smart card
communication, please try again.
0x80100030 -2146435024 Requested key file does not exist
0x80100065 -2146434971 Card reader cannot communicate with card due to
configuration conflicts of manufacturer information
0x80100066 -2146434970 Card has no response for reset operation
0x80100067 -2146434969 Card is power off
0x80100068 -2146434968 The card is repositioned. The shared information is invalid.
0x80100069 -2146434967 The card is disconnected.
0x8010006A -2146434966 Access denied due to existing security settings.
0x8010006B -2146434965 PIN code is not verified, access denied.
0x8010006C -2146434964 The maximum numbers of PIN verifications are reached.
Access denied.
0x8010006D -2146434963 The last card file has been reached. There is no more files
ROCKEY6 SMART User Manual V1.3


94
could be visited.
0x8010006E -2146434962 Operation is stopped by the user.
0x8010006F -2146434961 The smart card PIN is not configured.
0xA0100001 -1609564159 The file already exists.
0xA0100002 -1609564158 Card internal storage operation error.
0xA0100003 -1609564157 The user provides an invalid CLA.
0xA0100004 -1609564156 The user provides an invalid INS.
0xA0100005 -1609564155 The virtual machine address is overflow/ normal
0xA0100006 -1609564154 Divide by zero error
0xA0100007 -1609564153 The card is not plugged into the correct position.
0xA0100008 -1609564152 The card is in unknown state.
0xA0100009 -1609564151 The card is not opened.
0xA010000A -1609564150 Unknown command
0xA010000B -1609564149 The reset times of setting super password is 0
0xA010000C -1609564148 Opened too many devices.
0xA010000D -1609564147 Invalid instruction error.
0xA01000FF -1609563905 The card still has data needing to be returned.
Virtual Device Error Codes
0xA0101001 -1609560063 Failed to create virtual card file
0xA0101002 -1609560062 Failed to open virtual card file
9.10 Authorization
Authorizationtypes
0 Password is unverified
1 Reseller code is verified
ROCKEY6 SMART User Manual V1.3


95
2 Manufacturer code is verified
3 Remote update password is verified
4 Super password is verified

Requiredauthoritylevelsforvariousoperations
GET_CARD_INFO 0, 1, 2, 3, 4
GET_HARDWARE_INFO 0, 1, 2, 3, 4
GET_MANAGER_CODE 0, 1, 2, 3, 4
GET_CARD_PRIVILEGE 0, 1, 2, 3, 4
GET_REMOTE_INFO 0, 1, 2, 3, 4
SET_REMOTE_INFO 0, 1, 2, 3, 4
CHECK_REMOTE_INFO 0, 1, 2, 3, 4
GET_CURRENT_DIR 0, 1, 2, 3, 4
SET_CURRENT_DIR 0, 1, 2, 3, 4
GET_CURRENT_FILE 0, 1, 2, 3, 4
SET_CURRENT_FILE 0, 1, 2, 3, 4
GET_PARENT_DIR 0, 1, 2, 3, 4
SET_PARENT_DIR 0, 1, 2, 3, 4
LIST_DIR 0, 4, (4 could list hidden executable files)
READ_FILE 0, 1, 2, 3, 4
WRITE_FILE 0, 1, 2, 3, 4(executable file, internal used only files
are required level 4)
FORMAT_CARD 1, 2, 4
CREATE_DIR 0, 1, 2, 3, 4
CREATE_FILE 0, 1, 2, 3, 4(executable files, internal use only file
requires level 4)
ROCKEY6 SMART User Manual V1.3


96
REMOVE_DIR 0, 1, 2, 3, 4(required DIR is empty)
REMOVE_FILE 0, 1, 2, 3, 4(executable files, internal use only file
requires level 4)
RANDOM 0, 1, 2, 3, 4
RUN 0, 1, 2, 3
CHECK_SUPER_PASS 0, 1, 2, 3, 4
SET_SUPER_PASS 4
GET_UPGRADE_REMOTE_PASS 4
CHECK_AGENT_PASS 0, 1, 2, 3, 4
CHECK_MANUFACTURER_PASS 0, 1, 2, 3, 4
SET_HARDWARE_INFO 2
SET_MANAGER_CODE 2
SET_AGENT_PASS 2
SET_MANUFACTURER_PASS 2
DESENC 0, 1, 2, 3, 4
DESDEC 0, 1, 2, 3, 4
RSAGENKEY 4
RSAENC 0, 1, 2, 3, 4
RSADEC 0, 1, 2, 3, 4
GETFREESPACE 0, 1, 2, 3, 4
SETCOUNTER 4
STEPCOUNTER 0, 1, 2, 3, 4



ROCKEY6 SMART User Manual V1.3


97

Chapter 10 API Reference and Samples
10.1 API Reference
The API is a built-in interface that is used for the program communications between the
developers applications and the ROCKEY6 SMART dongle. It is provided to the developer by using a
corresponding develops language. For Microsoft Visual C++developers, there are two methods to use
them: static link and dynamic link. When static link is used, you need to add the file Dic32u.lib and
Dic32.h into the project.

There are a total of 8 API interfaces in Dic32u.DLL. The following table provides a description
(please also see Chapter9)
Table101APIDescription
ROCKEYSMART API
Interface
Main Function Description
DIC_Find Find card reader devices connected to the PC
DIC_Open Open selected card reader
DIC_Close Close selected card reader
DIC_Command Dongle operation instruction function is the main function
for sending the instructions to the dongle
DIC_Get Get returned data sub function
DIC_Set Set inputted data sub function
DIC_GetVersion Get current version number of dynamic library
ROCKEY6 SMART User Manual V1.3


98

10.2 Sample01 Fundamental Framework
DIC_Find, DIC_Open and DIC_Close are the three basic API operations for find open and
close the dongle. DIC_Find returns the number of the smart card reader drivers installed. Please note
that even though there is no ROCKEY6 SMART dongle connected to the PC, the return value for
DIC_Find is NOT zero, for its driver is already installed. To identify whether a ROCKEY6 SMART is
plugged into the PC, DIC_Open needs to be run. The parameters of DIC_Open and DIC_Close
are the dongle handlers that are counted from 0. Once a dongle is unlocked, the root directory is
shown.

The following example is using the static link to connect DLL. Its corresponding project
is<Samples\API32VC\VC6\Sample01>.
num= DI C_Fi nd( ) ; / / Number of dongl e
i f ( num<= 0)
{
pr i nt f ( " No dongl e f ound\ n" ) ;
r et ur n;
}
pr i nt f ( " Open t he Dongl e\ n" ) ;
f or ( i =0; i <num; i ++)
{
hi c = DI C_Open( i , NULL) ;
/ / Do not have t o know t he name of t he dongl e,
/ / i nput NULL
ROCKEY6 SMART User Manual V1.3


99
i f ( hi c >= 0)
br eak; / / St op sear chi ng once one dongl e i s f ound.
}
i f ( i == num)
{
pr i nt f ( " No dongl e wi t h connect ed Dongl e f ound\ n" ) ;
r et ur n;
}
i f ( er r code ! = SCARD_S_SUCCESS)
{
pr i nt f ( " Er r or code: %08x\ n" , er r code) ;
r et ur n;
}
/ / . . .
/ / Speci f i c dongl e oper at i ons
/ / . . .

pr i nt f ( " Cl ose t he Dongl e\ n" ) ;
er r code = DI C_Cl ose( hi c) ;
i f ( er r code ! = SCARD_S_SUCCESS)
{
pr i nt f ( " Er r or code: %08x\ n" , er r code) ;
r et ur n;
}

ROCKEY6 SMART User Manual V1.3


100
10.3 Sample02 Traversing Dongles
If a PC has many USB ports or connects to a USB HUB, then more than one ROCKEY6 SMART
dongle could be present. More importantly, those dongles could be simultaneously used on the same
PC without any conflicts. The maximum numbers of concurrent dongles is 16. The software developer
must determine how to distinguish between multiple attached ROCKEY6 SMART dongles. We would
recommend the developer to use the dongle management ID information to do this, as this ID is always
unique for each customer account. (Unless the customer requests a different ID)
DIC_Find is used to find the number of card reader drivers on the system. A successful operation
of DIC_Open shows the existence of a dongle. A complete example project is in <
Samples\API32VC\VC6\Sample02>.

char r eader _name[ 256] ; / / The name of t he dongl e
num= DI C_Fi nd( ) ;
pr i nt f ( " %d\ n" , num) ; / / Out put shoul d be 6, i f dr i ver s i nst al l ed pr oper l y.
i f ( num<= 0)
{
pr i nt f ( " No dongl e f ound\ n" ) ;
r et ur n;
}
/ / Tr aver se begi ns
f or ( i =0; i <num; i ++)
{
pr i nt f ( " Open t he Dongl e: " ) ;
hi c = DI C_Open( i , r eader _name) ;
i f ( hi c < 0)
{
ROCKEY6 SMART User Manual V1.3


101
i f ( hi c == SCARD_W_REMOVED_CARD)
{
pr i nt f ( " No Dongl e f ound\ n" ) ;
cont i nue;
}
pr i nt f ( " Er r or code: %08x\ n" , hi c) ;
r et ur n;
}
pr i nt f ( " %s\ n" , r eader _name) ; / / Out put t he name of t he dongl e
/ / . . .
/ / Speci f i c Dongl e oper at i ons
/ / . . .

pr i nt f ( " Cl ose t he Dongl e %d\ n" , i ) ;
er r code = DI C_Cl ose( i ) ;
i f ( er r code ! = SCARD_S_SUCCESS)
{
pr i nt f ( " Er r or code: %08x\ n" , er r code) ;
r et ur n;
}
}

10.4 Sample03 Dynamic Linked Mode
Loading DLL is an optional link mode that is unnecessary to use lib files. The complete example
project is in <Samples\API32VC\VC6\Sample03>.
ROCKEY6 SMART User Manual V1.3


102
/ / Def i ne t he usef ul f unct i ons
t ypedef i nt ( WI NAPI *f DI C_Fi nd) ( ) ;
t ypedef i nt ( WI NAPI *f DI C_Open) ( i nt hi c, char * r eader _name) ;
t ypedef i nt ( WI NAPI *f DI C_Cl ose) ( i nt hi c) ;
t ypedef i nt ( WI NAPI *f DI C_Cr eat e) ( char * f i l ename, char * mf name, char * at r ,
WORD at r l en) ;
t ypedef i nt ( WI NAPI *f DI C_Get Ver si on) ( char * ver ) ;
t ypedef i nt ( WI NAPI *f DI C_Command) ( i nt hi c, i nt cmd, voi d* cmddat a) ;
t ypedef i nt ( WI NAPI *f DI C_Get ) ( voi d* xdat a, i nt p1, i nt p2, char * buf f er ) ;
t ypedef i nt ( WI NAPI *f DI C_Set ) ( voi d* xdat a, i nt p1, i nt p2, i nt p3, char *
buf f er ) ;

/ / Funct i on def i ni t i on
HI NSTANCE hDl l = NULL;
/ / Dynami c l i br ar y handl e
f DI C_Fi nd dDI C_Fi nd;
f DI C_Open dDI C_Open;
f DI C_Cl ose dDI C_Cl ose;
f DI C_Cr eat e dDI C_Cr eat e;
f DI C_Get Ver si on dDI C_Get Ver si on;
f DI C_Command dDI C_Command;
f DI C_Get dDI C_Get ;
f DI C_Set dDI C_Set ;
voi d mai n( )
{
i nt er r code, num, hi c, i ;
/ / Load dynami c l i br ar y
ROCKEY6 SMART User Manual V1.3


103
hDl l = LoadLi br ar y( " DI C32u. DLL" ) ;
i f ( hDl l == NULL) r et ur n;
dDI C_Fi nd = ( f DI C_Fi nd) Get Pr ocAddr ess( hDl l , " DI C_Fi nd" ) ;
dDI C_Open = ( f DI C_Open) Get Pr ocAddr ess( hDl l , " DI C_Open" ) ;
dDI C_Cl ose = ( f DI C_Cl ose) Get Pr ocAddr ess( hDl l , " DI C_Cl ose" ) ;
dDI C_Cr eat e = ( f DI C_Cr eat e) Get Pr ocAddr ess( hDl l , " DI C_Cr eat e" ) ;
dDI C_Get Ver si on = ( f DI C_Get Ver si on) Get Pr ocAddr ess( hDl l ,
" DI C_Get Ver si on" ) ;
dDI C_Command = ( f DI C_Command) Get Pr ocAddr ess( hDl l , " DI C_Command" ) ;
dDI C_Get = ( f DI C_Get ) Get Pr ocAddr ess( hDl l , " DI C_Get " ) ;
dDI C_Set = ( f DI C_Set ) Get Pr ocAddr ess( hDl l , " DI C_Set " ) ;
pr i nt f ( sear chi ng t he dongl e: " ) ;
num= dDI C_Fi nd( ) ;
pr i nt f ( " %d\ n" , num) ;
i f ( num<= 0)
{
pr i nt f ( " No dongl e f ound\ n" ) ;
r et ur n;
}
pr i nt f ( " Open t he dongl e\ n" ) ;
f or ( i =0; i <num; i ++)
{
hi c = dDI C_Open( i , NULL) ;
/ / Dont need t o know t he name of dongl e, set NULL
i f ( hi c >= 0) br eak;
/ / St op t he sear chi ng once one i s f ound
}
ROCKEY6 SMART User Manual V1.3


104
i f ( i == num)
{
pr i nt f ( " No dongl e connect ed t o Dongl e f ound\ n" ) ;
r et ur n;
}
/ / . . .
/ / Speci f i c dongl e oper at i ons
/ / . . .
pr i nt f ( " Cl ose t he dongl e\ n" ) ;
er r code = dDI C_Cl ose( hi c) ;
/ / Unl oad dynami c l i br ar y
Fr eeLi br ar y( hDl l ) ;
}
10.5 Sample04 Get Manufacture and Volume Information
Software developers specify both volume and software developer information. Developers also
decide how to use such information. In general we recommend that developers write their company
information into the software developer information file. In doing so after a DIC_Open command, you
may get this information and use it to identify your dongle.

DIC_Command is the core API through which most of the functions works. It has three
parameters: dongle handle, the command to be executed, and data buffer related to said command.
The second parameter is already defined as a macro for ease of use.

For example, macro GET_CARD_INFO is used to read software developer and volume
information.
ROCKEY6 SMART User Manual V1.3


105

DIC_Get is an auxiliary API responsible for helping the user obtains information from the data
buffer. Its second parameter is also pre-defined as a macro. If the second parameter is ATR, it refers
to software developer information. If the second parameter is VOLUME, it refers to volume
information. The third parameter defines the return mode of the data. BY_VALUE means the
information is returned as the return value of DIC_Get. BY_ARRAY means the information returned
is stored in the buffer, and the return value of DIC_Get is the content length of the buffer. When using
DIC_Get, if the macro is a piece of string information of software developer information or volume,
the data is always returned by BY_ARRAY, no matter how the returned mode is set. Then, the return
value of DIC_Get is the length of software developer or volume information in the buffer. Please refer
to <Samples\API32VC\VC6\Sample04>.

i nt i , num, hi c, er r code;
char cmddat a[ 256] ; / / command buf f er
char buf f er [ 256] ; / / user buf f er
num= DI C_Fi nd( ) ;
f or ( i =0; i <num; i ++)
{
hi c = DI C_Open( i , NULL) ;
i f ( hi c >= 0) br eak; / / St op sear chi ng once one i s f ound
}
i f ( i == num) r et ur n;
er r code = DI C_Command( hi c, GET_CARD_I NFO, cmddat a) ;
DI C_Get ( cmddat a, ATR, BY_ARRAY, buf f er ) ;
/ / Tr ansf er ATR f r omcmddat a t o buf f er
pr i nt f ( sof t war e devel oper i nf or mat i on: %s\ n" , buf f er ) ;
DI C_Get ( cmddat a, VOLUME, BY_ARRAY, buf f er ) ;
ROCKEY6 SMART User Manual V1.3


106
/ / Tr ansf er vol ume i nf or mat i on f r omcmddat a t o buf f er
pr i nt f ( " Mai n vol ume: %s\ n" , buf f er ) ;
er r code = DI C_Cl ose( hi c) ;

10.6 Sample05 Get Manufacture Time, Hardware Serial Number,
Shipping Time, and COS Version
Hardware information includes factory time, hardware serial number, ship time and COS version.
Such information is available to the macro of GET_HARDWARE_INFO in DIC_Command. And the
corresponding macros in DIC_Get can also get the information items: FACTORY_TIME (The time
that the dongle was produced by the manufacturer.), HARD_SERIAL (The hardware serial number is
a globally unique identifier), SHIP_TIME (The ship time may be related to the software developer
warranty), and COS_VERSION (COS version of the card).

The following example demonstrates another mode of the DIC_Get application. If the return
mode is BY_VALUE, the last parameter can be set to NULL. You may get the parameter from the
return value. Please refer to <Samples\API32VC\VC6\Sample05>.
i nt i , num, hi c, er r code;
char cmddat a[ 256] ; / / Command buf f er
DWORD Fact or yTi me, Har dSer i al , Shi pTi me, COSVer si on;
num= DI C_Fi nd( ) ;
f or ( i =0; i <num; i ++)
{
hi c = DI C_Open( i , NULL) ;
i f ( hi c >= 0) br eak; / / St op sear chi ng once one i s f ound
ROCKEY6 SMART User Manual V1.3


107
}
i f ( i == num) r et ur n;
er r code = DI C_Command( hi c, GET_HARDWARE_I NFO, cmddat a) ;
Fact or yTi me = DI C_Get ( cmddat a, FACTORY_TI ME, BY_VALUE, NULL) ;
Har dSer i al = DI C_Get ( cmddat a, HARD_SERI AL, BY_VALUE, NULL) ;
Shi pTi me = DI C_Get ( cmddat a, SHI P_TI ME, BY_VALUE, NULL) ;
COSVer si on = DI C_Get ( cmddat a, COS_VERSI ON, BY_VALUE, NULL) ;
pr i nt f ( " Fact or y t i me %08X\ n" , Fact or yTi me) ;
pr i nt f ( " Har dwar e ser i al number %08X\ n" , Har dSer i al ) ;
pr i nt f ( shi p t i me %08X\ n" , Shi pTi me) ;
pr i nt f ( " COS ver si on %c%c. %c%c\ n" , COSVer si on>>24, COSVer si on>>16,
COSVer si on>>8, COSVer si on) ;
er r code = DI C_Cl ose( hi c) ;
10.7 Sample06 Get Zone Code, Reseller Code, User Code 1 &User
Code 2
The macro GET_MANAGER_CODE of DIC_Command may get the management code
information of the dongle. ZONE, AGENT, USER1 and USER2 of DIC_Get represent
respectively zone code (country code of dongle), agent code (sales agent code of the dongle), and user
code (software developers have their own unique codes). Please refer to < Samples\API32VC
\VC6\Sample06>.
i nt i , num, hi c, er r code;
char cmddat a[ 256] ; / / Command buf f er
WORD Zone, Agent , User 1, User 2;
num= DI C_Fi nd( ) ;
ROCKEY6 SMART User Manual V1.3


108
f or ( i =0; i <num; i ++)
{
hi c = DI C_Open( i , NULL) ;
i f ( hi c >= 0) br eak; / / St op sear chi ng once one i s f ound
}
i f ( i == num) r et ur n;
er r code = DI C_Command( hi c, GET_MANAGER_CODE, cmddat a) ;
Zone = DI C_Get ( cmddat a, ZONE, BY_VALUE, NULL) ;
Agent = DI C_Get ( cmddat a, AGENT, BY_VALUE, NULL) ;
User 1 = DI C_Get ( cmddat a, USER1, BY_VALUE, NULL) ;
User 2 = DI C_Get ( cmddat a, USER2, BY_VALUE, NULL) ;
pr i nt f ( " Zone code %04x\ n" , Zone) ;
pr i nt f ( " Agent code %04x\ n" , Agent ) ;
pr i nt f ( " User code 1 %04x\ n" , User 1) ;
pr i nt f ( " User code 2 %04x\ n" , User 2) ;
er r code = DI C_Cl ose( hi c) ;

10.8 Sample07 Random Number
Random number generation is very important for many encryption algorithms. ROCKEY6 SMART
performs random number generation in the hardware. First of all, the length of the random number has
to be set through DIC_Set(maximum length of 16 bytes, set with RANDOM_SIZE macro), and then
calls the command RANDOM to get the random number. The random number is stored in cmddata.
Please refer to <Samples\API32VC\VC6\Sample07>.

ROCKEY6 SMART User Manual V1.3


109
i nt i , num, hi c, er r code;
char cmddat a[ 256] ;

num= DI C_Fi nd( ) ;
f or ( i =0; i <num; i ++)
{
hi c = DI C_Open( i , NULL) ;
i f ( hi c >= 0) br eak; / / St op sear chi ng once one i s f ound.
}
i f ( i == num) r et ur n;
DI C_Set ( cmddat a, RANDOM_SI ZE, BY_VALUE, 16, NULL) ; / / Set t he r andom
number l engt h
er r code = DI C_Command( hi c, RANDOM, cmddat a) ; / / Get r andomnumber
f or ( i =0; i <16; i ++) pr i nt f ( " %02X " , ( BYTE) cmddat a[ i ] ) ;
pr i nt f ( " \ n" ) ;
er r code = DI C_Cl ose( hi c) ;
10.9 Sample08 Super Password
The super password is for the developers and may never be shared with end users. Super
password verification is required for specific dongle operations.

The CHECK_SUPER_PASS in the DIC_Command are used for verifying the super password.
And the GET_CARD_PRIVILEGE macro will return the current privilege status of the dongle. Its
return value is one byte in length. Every bit of the byte represents a different privilege status.

ROCKEY6 SMART User Manual V1.3


110
We defined the following status of privilege.
Table102PrivilegeStatus
Macro Privilege Status
DICPR_NOPASS Password not verified status
DICPR_SUPERPASS Super password verified status
DICPR_REMOTEPASS Remote update password verified status

The SUPERPASS_STATUS macro of DIC_Get shows if super password verification is
successful. The return value of 1 represents successful verification, and 0 indicates super password
verification failure. REMOTEPASS_STATUS macro detects whether the remote update password
verification is successful or not. Please refer to <Samples\API32VC\VC6\Sample08>.
/ / Get pr i vi l ege i nf or mat i on of t he dongl e
er r code = DI C_Command( hi c, GET_CARD_PRI VI LEGE, cmddat a) ;
i f ( DI C_Get ( cmddat a, SUPERPASS_STATUS, BY_VALUE, NULL) )
pr i nt f ( " super passwor d i s ver i f i ed\ n" ) ;
el se pr i nt f ( " super passwor d i s i nval i d\ n" ) ;

/ / Super passwor d i s 8 FF
f or ( i =0; i <8; i ++) cmddat a[ i ] = ( char ) 0xFF;
er r code = DI C_Command( hi c, CHECK_SUPER_PASS, cmddat a) ;

/ / Get pr i vi l ege i nf or mat i on of t he dongl e
er r code = DI C_Command( hi c, GET_CARD_PRI VI LEGE, cmddat a) ;
i f ( DI C_Get ( cmddat a, SUPERPASS_STATUS, BY_VALUE, NULL) )
pr i nt f ( super passwor d i s ver i f i ed\ n" ) ;
el se pr i nt f ( super passwor d i s i nvi l d\ n" ) ;
ROCKEY6 SMART User Manual V1.3


111

/ / Updat i ng new super passwor d
/ / Put new super passwor d ( 0 1 2 3 4 5 6 7) i nt o t he buf f er
/ / Par amet er p3 of t he DI C_Set has maxi mum( 10 t i mes) t o t r y.
f or ( i =0; i <8; i ++) buf f er [ i ] = ( char ) i ;
DI C_Set ( cmddat a, SUPERPASS_DATA, BY_ARRAY, 10, buf f er ) ;
er r code = DI C_Command( hi c, SET_SUPER_PASS, cmddat a) ;

/ / Back t o t he nor mal user st at e
er r code = DI C_Cl ose( hi c) ;
er r code = DI C_Open( hi c, NULL) ;

/ / Tr y t he new super passwor d
f or ( i =0; i <8; i ++) cmddat a[ i ] = ( char ) i ;
er r code = DI C_Command( hi c, CHECK_SUPER_PASS, cmddat a) ;

/ / Get pr i vi l ege i nf or mat i on of t he dongl e
er r code = DI C_Command( hi c, GET_CARD_PRI VI LEGE, cmddat a) ;
i f ( DI C_Get ( cmddat a, SUPERPASS_STATUS, BY_VALUE, NULL) )
pr i nt f ( " super passwor d i s ver i f i es\ n" ) ;
el se pr i nt f ( " super passwor d i s i nval i d\ n" ) ;

10.10 Sample09 Directories and Files
This section covers directory and file operations. The complete example is in <Samples\API32VC\
VC6\Sample09>.
ROCKEY6 SMART User Manual V1.3


112

FormatFileSystem
The macro FORMAT_CARD in DIC_Command is to format the file system on the condition that
the super password has been verified and the volume and software developer information has been
set.

char dat a[ 256] ;
/ / 1. Change pr i vi l ege t o super user ( For mat oper at i on i s onl y avai l abl e
t o super user s)
f or ( i =0; i <8; i ++) dat a[ i ] = ( char ) 0xf f ;
/ / By def aul t , t he super passwor d i s 8 FFs.
er r code = DI C_Command( hi c, CHECK_SUPER_PASS, dat a) ;
/ / 2. New vol ume and sof t war e devel oper i nf or mat i on can and can onl y be set
/ / Whi l e f or mat t i ng.
DI C_Set ( dat a, VOLUME, BY_ARRAY, 0, " DI CSYSTEM" ) ;
DI C_Set ( dat a, ATR, BY_ARRAY, 0, " DI C Co. " ) ;
/ / 3. For mat
er r code = DI C_Command( hi c, FORMAT_CARD, dat a) ;

DirectoryOperations
DIR_Set, DIR_Get and DIR_ID of DIC_CLASS and DIC_NAME can set and read the
directory ID, class, and name respectively, while FILE_NO defines the file number. CREATE_DIR
and LIST_DIR in DIC_Command creates and lists the directory respectively. The list directory
command enumerates all the directories until an error is returned indicating there are no more
directories or files under the current directory.
/ / Cr eat e a di r ect or y wi t h I D 0x1000, t he l ong f i l e name i s Di r 1
ROCKEY6 SMART User Manual V1.3


113
DI C_Set ( dat a, FI LL, 256, 0, NULL) ; / / Cl ear
DI C_Set ( dat a, DI R_I D, BY_VALUE, 0x1000, NULL) ;
DI C_Set ( dat a, DI R_CLASS, BY_VALUE, 0xf f , NULL) ;
DI C_Set ( dat a, DI R_NAME, BY_ARRAY, 0, " Di r 1" ) ;
er r code = DI C_Command( hi c, CREATE_DI R, dat a) ;
/ / Li st di r ect or y, l i st al l f i l es and di r ect or i es under t he cur r ent di r ect or y
/ / Not e: l i st di r ect or y i n t he r oot di r ect or y. The f i r st f i l e i s t he r oot
f i l e, and t he 2nd one i s
/ / t he sof t war e devel oper i nf or mat i on f i l e
f or ( i =0; i <255; i ++)
{
DI C_Set ( dat a, FI LE_NO, BY_VALUE, I , NULL) ;
er r code = DI C_Command( hi c, LI ST_DI R, dat a) ;
i f ( er r code ! = SCARD_S_SUCCESS) br eak;
di r i d = DI C_Get ( dat a, DI R_I D, BY_VALUE, NULL) ;
DI C_Get ( dat a, DI R_NAME, BY_ARRAY, buf f er ) ;
pr i nt f ( " %04x %s\ n" , di r i d, buf f er ) ;
}
/ / SET_CURRENT macr o of DI C_Command ent er s t he sub- di r ect or y.
/ / I t s par amet er i s t he I D of t he sub- di r ect or y. SET_PARRENT_DI R i s used
t o r et ur n t o t he
/ / upper di r ect or y wi t hout usi ng any par amet er s
/ / Ent er i ng t he di r ect or y 0x1100
DI C_Set ( dat a, DI R_I D, BY_VALUE, 0x1100, NULL) ;
er r code = DI C_Command( hi c, SET_CURRENT_DI R, dat a) ;
/ / Ret ur n t o t he upper di r ect or y, t he val ue of t he dat a i s voi d
er r code = DI C_Command( hi c, SET_PARENT_DI R, dat a) ;
ROCKEY6 SMART User Manual V1.3


114

DataFileOperations
The macro CREAT_FILE of DIC_Command creates files, WRITE_DATA writes data into a file,
sET_CURRENT_FILE selects a file, READ_FILE reads the selected file, and REMOVE_FILE
deletes file(s).

The parameter settings for the operation of writing to files are special for the DIC_Set application,
the convention is:
DI C_Set ( dat a, WRI TE_DATA, wr i t e_si ze, wr i t e_of f set , wr i t e_dat a) ;
The convent i on of t he par amet er set t i ngs of r eadi ng f i l es f or DI C_Set i s:
DI C_Set ( dat a, READ_DATA, r ead_si ze, r ead_of f set , NULL)
/ / Cr eat e f i l e
DI C_Set ( dat a, FI LL, 256, 0, NULL) ; / / Cl ear
DI C_Set ( dat a, FI LE_I D, BY_VALUE, 0x0033, NULL) ; / / Fi l e I D
DI C_Set ( dat a, FI LE_CLASS, BY_VALUE, 0xf f , NULL) ; / / Fi l e t ype
DI C_Set ( dat a, FI LE_ATTRI BUTE, BY_VALUE, FI LEATTR_NORMAL, NULL) ; / / Dat a
f i l e at t r i but e i s gener al l y set as FI LEATTR_NORMAL
DI C_Set ( dat a, FI LE_SI ZE, BY_VALUE, 20, NULL) ; / / Fi l e si ze
DI C_Set ( dat a, FI LE_NAME, BY_ARRAY, 0, " Fi l e1" ) ;
er r code = DI C_Command( hi c, CREATE_FI LE, dat a) ;
/ / Wr i t e 20- byt e i nf or mat i on t o t he f i l e
/ / Not e: The new f i l e j ust cr eat ed i s aut omat i cal l y set t o be t he cur r ent
f i l e,
/ / unnecessar y t o set i t agai n.
DI C_Set ( dat a, WRI TE_DATA, 20, 0, " abcdef ghi j kl mnopqr st " ) ;
er r code = DI C_Command( hi c, WRI TE_FI LE, dat a) ;
/ / Sel ect t he j ust cr eat ed f i l e wi t h I D 0x0033
ROCKEY6 SMART User Manual V1.3


115
DI C_Set ( dat a, FI LE_I D, BY_VALUE, 0x0033, NULL) ;
er r code = DI C_Command( hi c, SET_CURRENT_FI LE, dat a) ;
/ / Read t he f i l e and di spl ay i t s l engt h and cont ent
DI C_Set ( dat a, READ_DATA, 20, BY_VALUE| 0, NULL) ;
er r code = DI C_Command( hi c, READ_FI LE, dat a) ;
r eadsi ze = DI C_Get ( dat a, READ_DATA, BY_VALUE, buf f er ) ;

/ / Del et e t he cur r ent f i l e
er r code = DI C_Command( hi c, REMOVE_FI LE, dat a) ;


10.11 Sample10 Remote Update
See also Chapter 5 Remote Update Management in <<User Manual>>; the complete example is
in<Samples\API32VC\VC6\Sample10>

10.12 Sample11 Write and Execute Program
Users can develop their own programs inside the dongle. It is also one of the most important
security features of the dongle. Feitian have provided IDE for users to develop and store their own
programs inside the dongle.

We use the Keil development environment to develop internal programs of the dongle and then
convert compiled *.bin files into C array by using Tools\Binary >C of the ROCKEY6 SMART IDE,
ROCKEY6 SMART User Manual V1.3


116
and also insert it into the program, as well as burning the virtual card files produced by the Keil
debugger simulator into the real device.

Executable files of the dongle must be written under the dongle root directory and they can only be
accessed after super password verification. The complete example is in < Samples\API32VC
\VC6\Sample11>.

10.13 Sample12 Double-Precision Point Calculation
This example will introduce how to perform float point calculations inside the card, and return the
results to the external program. The complete example project locates in the < Samples
\API32VC\VC6\Sample12>.

10.14 Sample13 Secure File Transfer
Regarding secure File Transfer, please also see section 5.2 Secure File Transfer in <<User
Manual>>for details. The complete example project is in <Samples\API32VC\VC6\Sample13>.

10.15 Sample14 DES and 3DES Encryption and Decryption
The ROCKEY6 SMART dongle with model HID has the features of DES and 3DES encryption
and decryption. The steps for using them are as follows:
- Generating internal data files (super password is required)
ROCKEY6 SMART User Manual V1.3


117
- Writing DES or 3DES key (super password is required)
- The encryption and decryption procedures are all based on file ID and key ID. That is, when
encryption occurs, all data length that is not length in 8 multiples will be automatically filled into
lengths in 8 multiples. Therefore, all encrypted data is length in 8 multiples. When decryption occurs,
the dongle would restore the original data by removing all filled in data.

Note:
The difference between DES key and 3DES key is their data length: the DES key length is 8 bytes.
In contrast, the 3DES key length is 16 bytes.
The data structure for writing in DES key and 3DES key is:
* The DES key length is 10 bytes Key ID (1 byte) +key length (1byte, the value should be 8) +
key (8 bytes)
* The 3DES key length is 18 bytes -- Key ID (1byte) +key length (1byte, the value should be 16)
+key (16 bytes)

For a complete example, please refer to <Samples\API32VC\VC6\Sample14>. In this example,
there is only a DES key and a 3DES key. In most cases, developers can freely set their file size and the
keys accordingly.
10.16 Sample15 RSA Encryption and Decryption
In the HID model ROCKEY6 SMART dongle, the procedures for using RSA functions is as
follows:
Generating RSA key pairs (super password is required)
Encrypting and decrypting data according to public key ID and private key ID.

Note:
ROCKEY6 SMART User Manual V1.3


118
The key length is calculated in bits. Currently, it can support the key length of 1024 bits and 512
bits.
The default value of e is 65537, and it is not modifiable.
When data is encrypted, to prevent encrypting data bigger than n, please set the most significant
bit for plain text to zero.

The complete example is in <Samples\API32VC\VC6\Sample15>.

10.17 Sample16 Counter Usage
Counter is a method that results in limiting the use times of the software by a developer. Once a
counter is setup, the developer can control and define the use times decreasing progressively. The
procedure is as follows:
- Setting up the counter (super password is required)
- The counter is decreased every time that the developer defined software procedure is performed.

If a developer sets the counter to zero, then it means the software can be used without times
limitation. The default state for a formatted dongle is use without times limitation.

If the counter is deducted to 1, then the dongle cannot be used any more. It has to be sent back
and reset by the developer. Usually, a developer would use the following processes to reset a dongle
counter:
After successfully verifying the super password, reset the counter to zero or any other numbers
rather than 1.
Formatting dongle, the counter would be automatically set to zero. However, this method is not
ROCKEY6 SMART User Manual V1.3


119
normally used.

The complete example project is in <Samples\API32VC\VC6\Sample16>.

10.18 Sample17 Reading the Remaining Space
In order to manage the dongle memory space well, ROCKEY6 SMART provides the developer an
interface to check the dongle remaining space. The complete example is in: <Samples\API32VC
\VC6\Sample17>.
10.19 Sample18 Unlock the Dongle According To the Manufacture
ID
The developer may have many different dongles from different manufactures therefore they need
to manage their own dongle from the management code. ROCKEY6 SMART provides an API
DIC_FindByMgrCode. Developers may use this function to replace DIC_Find and also find the
dongle with the same management code by using this function. This function increased a management
code parameter compared to DIC_Find which is used by developers for inputting their own
management code. Developers may fill the structure DICST_ManagerCode and send into
DIC_FindByMgrCode, as well as they can define a buffer as follows:

Unsigned Char mgnCode[ ]={0x56,0x00,0x02,0x00,0xee,0xff,0xee,0xff};//Make sure the order of
the bytes, the management code here is 0056 0002 FFEE FFEE.

The complete example is in: <Samples\API32VC\VC6\Sample18>.
ROCKEY6 SMART User Manual V1.3


120

PART 3 Advanced Section
This part introduces RSA and DES encryption and decryption as well as APDU and COS system
invoked usage. After over viewing this section the user will use ROCKEY6 SMART to improve program
security level and also perform some flexible management.

Chapter11,SystemCallFunctionUsage
ROCKEY6 SMART provides a set of system call functions. The user can use them when they are
compiling an external program, (executed in the smart card) such as file operation, fetching system
information, and float point function etc.

Chapter12,AdvancedApplicationoftheFileSystem
This chapter introduces the file filter and APDU command and its applications. Filter file is a special
executable file that can filter some information. This chapter will describe how to create a filter file to
reach maximum-security control.

Chapter13COSSystemCallReference
In the process of compiling the smart card program, the dongle default functions are used. Those
functions are performed by system calls.



ROCKEY6 SMART User Manual V1.3


121

Chapter 11 System Call Function Usage
ROCKEY6 SMART provides five parts of the system call. (1) System function - such as
input/output and COS security mechanism, etc., (2) File operation - such as open file, read file and
write file. This part is fundamental to accessing the COS file system from external programming, (3)
Float-precision calculation - such as some simple calculations; plus, minus, multiplication, division and
some complicated extensive float-precision calculation, (4) Encryption and decryption - ROCKEY6
SMART provides three main encryption and decryption algorithms: RSA, DES, TDES and other
algorithms can be extended by self-defined algorithms (5) Utility of system call - such as random
number, request remote update marks. Some external applications can invoke the FEITIAN COS
system service to extend their functions. For more detail, please refer to <<Chapter 13 COS System
Call Reference >>

Constitution of COS (Card Operating System) has been already introduced in this handbook. The
following are problems that may appear in the development process:

Data file has an internal use attribute. It means this kind of file only can be operated in the dongle.
System function provides six functions to perform the file operation. The file without marked internal
use also can be accessed by an executable file. Please Note: The executable file can access the data
file only when the file category of an executable file and a data file are in the same situation, and the
security level of the executable file must be greater or equal to the data file.

If user performed some other manipulations after selecting data the selection will fail. They have to
re-choose next time in such case.

ROCKEY6 SMART User Manual V1.3


122
11.1 Memory management
When using KEIL to program ROCKEY6 SMART, because the ROCKEY6 SMART memory is
pre-defined, users do not need to allocate the memory by themselves. Primarily, data, idata, and
xdataare memories available to the user. "data", internal data area with direct addressing, is 128
bytes and has the fast speed to access variables; "idata", internal data area with indirect addressing, is
256 bytes and has ability to access all of the internal address spaces; "xdata" is the external data area
with 64k bytes. In such manner, the big buffer should be defined in xdata area as following:
unsi gned char xdat a buf [ 300] ;

As default, datum is stored in the data area therefore users can use the xdataarea to share the
datum. To transmit datum from one program to another you can use two methods, one is using syscall,
and the other is using the following method which is more convenient:
Code1:
voi d mai n( voi d)
{
unsi gned char xdat a *p=0;
memset ( p, 1, 128) ;
set _r esponse( 128, p) ;
exi t ( ) ;
}

Code2:
voi d mai n( voi d)
{
unsi gned char xdat a *p=0;
ROCKEY6 SMART User Manual V1.3


123
set _r esponse( 128, p) ;
exi t ( ) ;
}

The only difference between the two programs is code 2 has not performed a rewrite to buffer p.
Running code 2 generates 128 random numbers.(The numbers have not initialized in memory but are
not from the random function) however code 1 generates 128 number 1.This is the basic principle of
the sharing memory.

11.2 Fundamental Framework
Input, output and exit in ROCKEY6 SMART program is defined as:
byt e get _i nput ( I N byt e* pd, I N byt e of f set , I N byt e mode, I N byt e number )
byt e set _r esponse( I N byt e l en, OUT byt e *pd)
exi t ( )

Please Note:
In get_input function, mode represents type of input. For example, Replacing get_input
(&x1,0,1,1); to get_input(&x1,0,0,2); all represent inputting 2 bytes however the results are different.
The reason is that the order of bytes in the C51 program and the computer are opposite. If input word
(dword) into the program therefore mode should be assigned to 1(2).

C51 example fac.c
#i ncl ude " sys_api . h"
/ / Fact or i al Funct i on
ROCKEY6 SMART User Manual V1.3


124
i nt f un1( i nt a, i nt b, i nt *ab)
{
i nt a1, b1;
a1=a*a;
b1=b*b;
*ab=a1+b1;
}
/ / Mai n f unct i on
voi d mai n( )
{
i nt x1, x2, x12;
/ / Get t he f i r st i nput var i abl e
get _i nput ( &x1, 0, 1, 1) ;
/ / Get t he second var i abl e
get _i nput ( &x2, 2, 1, 1) ;
/ / Resul t s
f un1( x1, x2, &x12) ;
/ / Out put
set _r esponse( 2, &x12) ;
/ / Qui t pr ogr am
exi t ( ) ;
}

The above example demonstrates the fundamental method to develop ROCKEY6 SMART by
using Keil. Function get_inputobtains data after calculation and uses function set_responseto send
data back. Eventually, invoke function exit to quit.
ROCKEY6 SMART User Manual V1.3


125
11.3 File operation
There are five kinds of file operations in the ROCKEY6 SMART system call. They are shown in the
following table 11-1.
Table111FileOperationsystemfunction
System function Description
creat_file() Create a file or directory
delete_file() Delete the current file
open_file() Open a file/directory or return to
the up folder
write_file() Write data into the file
read_file() Read a file
get_file_infor() Get a file information

The definitions are as following:
bytecreat_file(INwordwFileID,INbytepbFileName,INbytebAttrib,INwordwSize)
byt e del et e_f i l e( )
byt e open_f i l e( I N byt e *pd, I N byt e open_mode)
byt e wr i t e_f i l e( I N wor d of f set , I N byt e *pd, I N wor d l ent h)
byt e r ead_f i l e( I N wor d of f set , OUT byt e *pd, I N wor d l ent h)
byt e get _f i l e_i nf or ( OUT byt e *pd, I N byt e mode)

Note:
The create_file function is used for creating a file. When the file does exist you cannot create
another. If creating a data file and it is a current file, users do not need to use the open_filefunction.
Open_file function is used for setting the current file to read, write and delete later.
ROCKEY6 SMART User Manual V1.3


126
Write_file function is used for writing file by offset, data and length. If the offset and the length are
greater than the length of the file then the length will increase automatically, however the input of the
offset should be less than the length of the file.
The Read_file function is similar to the write_file function, however if the offset and the length
are greater than the file length, only the valid part of the input file can be read into the buffer. If users
want to know the actual length of the input, they can use the get_file_info function to calculate the
size (Actual input size equals File length minus offset) and it will also fail when the offset is greater
than the file length.

C51 example file.c, a complete file operation program:
#i ncl ude " sys_api . h"
#i ncl ude <st r i ng. h>

voi d mai n( voi d)
{
byt e xdat a i s;
wor d xdat a f i l eI D;
byt e xdat a r esul t [ 50] ;
byt e xdat a i nf o[ 110] ;
wor d i d;
i d=0x3f 0a;
/ / I nput 102 byt es , t he f i r st 2 byt es ar e t he f i l e I D, t he r est ar e t he cont ent
get _i nput ( i nf o, 0, 0, 102) ;
/ / Get f i l e I D
memcpy( &f i l eI D, i nf o, 2) ;
/ / Open a di r ect or y by usi ng I D
i s = open_f i l e( &i d, 0) ;
ROCKEY6 SMART User Manual V1.3


127
/ / I f t he di r ect or y does not exi st
i f ( i s! =0)
{
/ / Cr eat e a new di r ect or y
cr eat _f i l e( i d, " myf i l e" , 0x20, 0xaa) ;
open_f i l e( &i d, 0) ;
}
/ / Open t he f i l e
i s= open_f i l e( &f i l eI D, 0) ;
/ / I f t he f i l e does not exi st
i f ( i s! =0)
{
/ / Cr eat e a f i l e
cr eat _f i l e( f i l eI D, " ef Fi l e" , 0x00, 0x64) ;
}
/ / I nput t he dat a i nt o t he dongl e 0 i s t he f i l e begi nni ng , 100 i s t he f i l e
l engt h
wr i t e_f i l e( 0, i nf o+2, 100) ;
/ / Read 20 byt es f r omt he of f set bei ng at 80 byt e
r ead_f i l e( 80, r esul t , 20) ;
/ / Del et e t hi s f i l e
del et e_f i l e( ) ;
/ / Ret ur n t o upper f ol der
open_f i l e( NULL, 2) ;
/ / Ret ur n t he r esul t s
set _r esponse( 20, r esul t ) ;
/ / Qui t
ROCKEY6 SMART User Manual V1.3


128
exi t ( ) ;
}

In the above example, Use the open_file function to open a folder. If the return is non-zero, it
means you cannot open it, and no such sub-folder exists in the current directory. If this happens then
use the create_file function to create the folder. After creating this successfully, use the
open_file function to set the folder as current. By similar operation, use the open_file function to
open a file, if this fails then use the create_file function to create a new file, after that is current.

11.4 Invoke Executable Programs
The ROCKEY6 SMART sys_recall function is used for invoking an executable file from another.
The definition is as follows:
byt e sys_r ecal l ( I N byt e val ue, I N byt e *pd, I N wor d l ent h, I N byt e *pdnext ) ;

The first parameter is an additional procedure when exiting the program. The second parameter is
the file ID which needs to run and is different to the external executable file. This is the executable file
ID rather than the file name. The last two parameters respectively are the length of input for the running
program and the file content. After having invoked and then entering the second program, the first
program quits and transmits the privilege to the next.

The following code syscall.c is an example of one external program calling another one to show
how to use the sys_recall() function.

When compiling the file test.c, rename the executable file as F2F4 (or any other names, as long
ROCKEY6 SMART User Manual V1.3


129
as the calling name is changed accordingly). The program will pass the data of 0-199 to the next
program for use.
#i ncl ude sys_api . h
#i ncl ude <st r i ng. h>

voi d mai n( voi d)
{
byt e xdat a i , y[ 200] ;
/ / t he i nvoked f i l e I D
byt e f i l eI D[ 2] ;
get _i nput ( f i l eI D, 0, 0, 2) ;
f or ( i =0; i <200; i =i +1)
{
y[ i ] =i ;
}
/ / I nvoke ext er nal pr ogr am
sys_r ecal l ( 5, f i l eI D, 200, y) ;
/ / qui t t he cur r ent pr ogr amand ent er t o t est . c
set _r esponse( 200, y) ;
exi t ( ) ;
}

test.cprogram:
voi d mai n( voi d)
{
i nt i ;
ROCKEY6 SMART User Manual V1.3


130
byt e xdat a i nf o[ 200] ;
get _i nput ( i nf o, 0, 0, 200) ; / / Get t he passed dat a 0- 199 f r omt he pr evi ous
pr ogr am
f or ( i =0; i <200; i ++)
{
i nf o[ i ] +=1;
}
set _r esponse( 200, i nf o) ; / / Out put dat a i s 1- 200
exi t ( ) ;
}

11.5 System Information and Security Mechanism
ROCKEY6 SMART provides the COS system functions and the relative functions of the security
mechanism. These functions are rather simple to use. Their return information is more than their inputs.
Therefore, it is necessary to set some variables for reading this information before calling them. There
are no restrictions for the types of variables. The following is the definitions:
byt e get _har d_i nf or ( byt e *pd) ;
byt e get _sys_i nf or ( byt e *pd) ;
byt e set _cl ass( byt e val ue) ;
byt e get _cl ass( byt e * pd) ;
byt e get _st at us( byt e *pd) ;
- get_hard_infor is used for obtaining hardware information, such as the manufacture time and the
serial number.
- get_sys_infor is used for obtaining system information, hardware version, user code.
ROCKEY6 SMART User Manual V1.3


131
- set_class & get_class are used for setting and getting current security information.
- get_status is used for getting external password verification status.

version.c shows how to get hardware information and system information
/ * ver si on. c */
#i ncl ude sys_api . h"
voi d mai n( voi d)
{
byt e xdat a back[ 200] ;
/ / manuf act ur e t i me ( 4byt es) ser i al number ( 4byt es)
get _sys_i nf or ( back) ; / / l en: 8
/ / har dwar e ver si on( 4 byt es) COS ver si on ( 4 byt es)
/ / Regi on code ( 2 byt es)
/ / Agent code ( 2 byt es) user code1( 2 byt es) user
/ / code2( 2 byt es)
get _har d_i nf or ( back+8) ; / / l en: 16
set _r esponse( 24, back) ;
exi t ( ) ;
}

read_info.c shows how to set and get current security information and external password
verification status
/ * r ead_i nf o. c */
#i ncl ude sys_api . h"

voi d mai n( voi d)
ROCKEY6 SMART User Manual V1.3


132
{
byt e cl ass;
/ / f i l e cl assi f i cat i on , cur r ent ext er nal ver i f i cat i on st at us
byt e secur i t y, secur i t y2;
/ / syst emsecur i t y l evel
byt e r esul t ;
/ / r et ur n val ue, 0 r epr esent s successf ul
byt e xdat a i nf o[ 128] ;

r esul t =0;
get _cl ass( i nf o) ;
cl ass=i nf o[ 0] ;
i f ( cl ass! =0xFF) / / I f t he pr ogr amcl assi f i cat i on i s not 0xFF
{
r esul t =1;
got o end;
}

secur i t y=0x06;
set _cl ass( secur i t y) ;
get _cl ass( i nf o) ;
secur i t y2=i nf o[ 1] ;
i f ( secur i t y! =secur i t y2)
{
r esul t =2;
got o end;
}
ROCKEY6 SMART User Manual V1.3


133

get _st at us( &cl ass) ;
i f ( cl ass! =0)
{
r esul t =3;
}

end:
set _r esponse( 1, &r esul t ) ;
exi t ( ) ;
}

11.6 RSA Encryption and Decryption
The ROCKEY6 SMART supports internal RSA system calls. The difference between supporting
internal RSA and external API invoked are (1) offering internal C51 directly invoked and (2) creating a
correct encryption key without super password verification.
byt e r sa_gen_key ( wor d pubKey, wor d KeyLen, wor d Pr i Key)
byt e r sa_enc( I N wor d f i l eI D, I N wor d l engt h, I N OUT voi d *dat a)
byt e r sa_dec( I N wor d f i l eI D, I N wor d l engt h, I N OUT voi d *dat a)
- rsa_gen_key can be used to generate encryption keys. As default, the private key generated by
rsa_gen_key cannot be read by any manipulation and can be created in any size internal file within
the private key which is named as the same as the original one, that means this file will be replaced
by the encryption key. It can be read by an internal program.
- rsa_enc is used for encrypting public key.
ROCKEY6 SMART User Manual V1.3


134
- rsa_dec is used for encrypting private key.
Actually, they are pair of reciprocal algorithms.

Program rsa.c demonstrates how to invoke RSA system call.
#i ncl ude sys_api . h"
#i ncl ude st r i ng. h"

voi d mai n( )
{
i nt r PubFi l eI D=0x1002; / / Rsa publ i c key I D
i nt r Pr i Fi l eI D=0x1004; / / Rsa pr i vat e key I D
wor d r KeyLengt h=1024; / / Rsa key l engt h
unsi gned char xdat a t Dat a[ 128] ; / / dat a t o encr ypt
unsi gned char xdat a out Dat a[ 256] ; / / out put dat a
i nt r et ;
/ / Obt ai n dat a
get _i nput ( t Dat a, 0, 0, 128) ;
/ / Gener at e key
r et =r sa_gen_key( r PubFi l eI D, r KeyLengt h, r Pr i Fi l eI D) ;
i f ( r et ! =0)
got o END;
memcpy( out Dat a, t Dat a, 128) ;
/ / RSA encr ypt i on
r et =r sa_enc( r PubFi l eI D, 128, t Dat a) ;
i f ( r et ! =0)
got o END;
memcpy( out Dat a, t Dat a, 128) ;
ROCKEY6 SMART User Manual V1.3


135
set _r esponse( 254, out Dat a) ;
exi t ( ) ;
END:
set _r esponse( 2, &r et ) ;
exi t ( ) ;
}

11.7 DES Encryption and Decryption
The ROCKEY6 SMART C51 system provides DES and 3DES encryption algorithms which are:
byt e des_enc( I N wor d f i l eI D, I N byt e keyI D, I N wor d l engt h, I N OUT voi d
*dat a) ;
/ / DES encr ypt i on f unct i on
byt e des_dec( I N wor d f i l eI D, I N byt e keyI D , I N wor d l engt h, I N OUT voi d
*dat a) ;
/ / DES decr ypt i on f unct i on
byt e t des_enc( I N wor d f i l eI D, I N byt e keyI D, I N wor d l engt h, I N OUT voi d
*dat a) ;
/ / 3DES encr ypt i on f unct i on
byt e t des_dec( I N wor d f i l eI D, I N byt e keyI D, I N wor d l engt h, I N OUT voi d
*dat a) ;

/ / 3DES decr ypt i on f unct i on
- Parameter fileID is the key file ID; keyID is the key ID; length is encryption/decryption, length here
is 8 integral multiples, data is the buffer to store the input and output data. The buffer will be covered
after the function is performed.
ROCKEY6 SMART User Manual V1.3


136
- DES and 3DES algorithms are the same as in API. The following codes demonstrate how DES &
3DES work.
DES:
#i ncl ude sys_api . h"
#i ncl ude <st r i ng. h>
voi d mai n( )
{
unsi gned char key[ 10] ={1, 8, 1, 2, 3, 4, 5, 6, 7, 8};
/ / def aul t key
unsi gned char xdat a dDat a[ 129] ;
/ / dat a t o encr ypt
i nt i ;
i nt r et ;
byt e Enc;
cr eat _f i l e( 0x1122, 0, 0, 10) ;
/ / cr eat e key
wr i t e_f i l e( 0, key, 10) ;
/ / wr i t e key
/ / obt ai n par amet er s
get _i nput ( &Enc, 0, 0, 1) ;
get _i nput ( key+2, 1, 0, 8) ;
get _i nput ( dDat a, 9, 0, 128) ;

i f ( Enc==0)
/ / encr ypt i on and decr ypt i on
dDat a[ 128] =des_enc( 0x1122, 01, 128, dDat a) ;
/ / use key 1122 keyI D i s 01
ROCKEY6 SMART User Manual V1.3


137
el se
dDat a[ 128] =des_dec( 0x1122, 01, 128, dDat a) ;
set _r esponse( 129, dDat a) ;
exi t ( ) ;
}

3DES:
#i ncl ude sys_api . h"
#i ncl ude <st r i ng. h>
voi d mai n( )
{
unsi gned char key[ 18] ={1, 16, 1, 2, 3, 4, 5, 6, 7, 8, 9, 10, 11, 12, 13, 14, 15, 16};
/ / def aul t key
unsi gned char xdat a dDat a[ 128] ; / / dat a t o encr ypt
byt e Enc;
cr eat _f i l e( 0x1122, 0, 0, 18) ; / / cr eat e key
wr i t e_f i l e( 0, key, 18) ; / / wr i t e key
/ / obt ai n par amet er s
get _i nput ( &Enc, 0, 0, 1) ;
get _i nput ( key+2, 1, 0, 16) ;
get _i nput ( dDat a, 17, 0, 128) ;

i f ( Enc==0) / / encr ypt i on and decr ypt i on
dDat a[ 128] =t des_enc( 0x1122, 01, 128, dDat a) ;
/ / use key 1122 keyI D i s 01
el se
dDat a[ 128] =t des_dec( 0x1122, 01, 128, dDat a) ;
ROCKEY6 SMART User Manual V1.3


138

set _r esponse( 129, dDat a) ;
exi t ( ) ;
}

11.8 Obtain Random Number
Random number can be used in many programs. ROCKEY6 SMART provides a random generator
which can generate random numbers, at most 16 bytes. The following example demonstrates the
generator. If the size is greater than 16 bytes, the program only returns the first 16 bytes.
#i ncl ude sys_api . h"

voi d mai n( voi d)
{
byt e addr ess[ 16] ;
byt e xdat a l en;
get _i nput ( &l en, 0, 0, 1) ;
/ / gener at es r andomnumber s accor di ng t o t he l engt h
get _r and( addr ess, l en) ;
set _r esponse( l en, addr ess) ;
exi t ( ) ;
}

ROCKEY6 SMART User Manual V1.3


139
11.9 Float Function Libraries Usage
There are basic float and complicated external float libraries in the ROCKEY6 SMART system call.
They are all in double precision. The ROCKEY6 SMART uses the math coprocessor to complete the
operation, the performance is better than the C51 internal float processor; therefore we recommend
users only use double precision.

Note:
The definition of double precision should be as byte a[8] because Keil does not support double
precision. Double and float type are the same, all 4 bytes.

Program double.c demonstrates how to use the basic float library.
#i ncl ude sys_api . h"
#i ncl ude <st r i ng. h>
voi d mai n( )
{
unsi gned char a1[ 8] ={0xA8, 0x57, 0xCA, 0x32, 0xC4, 0x71, 0x24, 0x40};
/ / 10. 2222
unsi gned char b1[ 8] ={0xF7, 0x06, 0x5F, 0x98, 0x4C, 0x55, 0x15, 0x40};
/ / 5. 3333
unsi gned char r esul t [ 72] ;
memset ( r esul t , 0, 72) ;
doubl e_add( a1, b1, r esul t ) ; / / pl us
doubl e_sub( a1, b1, r esul t +8) ; / / mi nus
doubl e_mul ( a1, b1, r esul t +16) ; / / mul t i pl y
doubl e_di v( a1, b1, r esul t +24) ; / / di vi si on
doubl e_compar e( a1, b1, r esul t +32) ; / / compar e
ROCKEY6 SMART User Manual V1.3


140
doubl e_abs( a1, r esul t +40) ; / / absol ut e val ue
doubl e_si n( a1, r esul t +48) ; / / si ne
doubl e_cos( a1, r esul t +56) ; / / cosi ne
doubl e_sqr t ( a1, r esul t +64) ; / / squar e
set _r esponse( 72, r esul t ) ;
exi t ( ) ;
}

Program extdouble.c demonstrates how to use the external float library.
#i ncl ude sys_api . h"
#i ncl ude st r i ng. h"
voi d mai n( )
{
unsi gned char a[ 8] , b[ 8] ; / / def i ne an ar r ay
unsi gned char xdat a uRet [ 105] ;
memset ( uRet , 0, si zeof ( uRet ) ) ; / / get par amet er s
get _i nput ( a, 0, 0, 8) ;
get _i nput ( b, 8, 0, 8) ; / / f l oat cal cul ai t on
doubl e_asi n( a, uRet ) ; / / ar c- si ne
doubl e_acos( a, uRet +8) ; / / ar c- cosi ne
doubl e_at an( a, uRet +16) ; / / ar c- t angent
doubl e_si nh( a, uRet +24) ; / / doubl e si ne
doubl e_cosh( a, uRet +32) ; / / doubl e cosi ne
doubl e_t anh( a, uRet +40) ; / / doubl e t angent
doubl e_cei l ( a, uRet +48) ; / / Mi ni mumi nt eger number gr eat er t han doubl e
doubl e_f l oor ( a, uRet +56) ; / / Maxi mumi nt eger number l ess t han doubl e
doubl e_exp( a, uRet +64) ; / / doubl e squar e
ROCKEY6 SMART User Manual V1.3


141
doubl e_l og( a, uRet +72) ; / / l ogar i t hm
doubl e_l og10( a, uRet +80) ;
doubl e_mod( b, a, uRet +88) ; / / mode

/ / r esul t s
set _r esponse( 104, uRet ) ;
exi t ( ) ;
}

11.10 Release Management
ROCKEY6 SMART provides software version management functionality in the C51 internal
system call, thus logical control is executed within the dongle with high security. We can combine the
internal program with these system calls.

ROCKEY6 SMART provides timer, counter and obtaining remote mark system call. They are
defined as:
byt e st ar t _t i mer ( )
byt e get _t i mer ( OUT dwor d * t i mer )
byt e set _count er ( byt e count er )
byt e st ep_count er ( )
byt e get _count er ( byt e* count er )
byt e get _r emot e_t ag ( OUT dwor d *Tag)

Program can trigger timer by start_timer. get_timer can be used for getting the interval which unit is
ROCKEY6 SMART User Manual V1.3


142
10MS.

Exampletimer.cdemonstrateshowtousetimer.
#i ncl ude sys_api . h"
voi d mai n( )
{
/ / i nput dat a f or t he l oop
unsi gned i nt i Ti mer ;
unsi gned l ong i ;
unsi gned l ong dTi mer ; / / r et ur n r un t i me
get _i nput ( &i Ti mer , 0, 1, 1) ;

/ / st ar t t i mer
st ar t _t i mer ( ) ;

f or ( i =0; i <i Ti mer ; i ++)
{

}

/ / get r un t i me
get _t i mer ( &dTi mer ) ;

/ / r et ur n
set _r esponse( 4, &dTi mer ) ;
exi t ( ) ;
}
ROCKEY6 SMART User Manual V1.3


143
In the program, users can use set_counter to set a number. Every time it is invoked it performs
step_counter. The dongle will be locked when the count equals zero.

Examplestep_counter.cdemonstrateshowtousethecounter:
#i ncl ude sys_api . h"
#i ncl ude <st r i ng. h>
voi d mai n( voi d)
{
wor d count er ;
i nt i ;
unsi gned l ong count =0;
/ / set number t o 5
set _count er ( 5) ;
/ / get t i mes of t he l oop
get _i nput ( &count er , 0, 1, 1) ;
f or ( i =0; i <count er ; i ++)
{
/ / decr ease count er
st ep_count er ( ) ;
}
/ / get count er
get _count er ( &count ) ;
/ / r et ur n count er
set _r esponse( 4, &count ) ;
exi t ( ) ;
}
ROCKEY6 SMART User Manual V1.3


144

In the program, users can use get_remote_tag to get a remote update mark and then the internal
code can control the program logic by the mark. Different marks match the corresponding codes.

Example Remote.c demonstrates how to get a remote update mark
#i ncl ude sys_api . h"
voi d mai n( )
{
dwor d dwTag;
/ / get r emot e updat e mar k
get _r emot e_t ag( &dwTag) ;
/ / do some l ogi cal cont r ol her e
/ / . . .
/ / out put r emot e updat e mar k
set _r esponse( 4, &dwTag) ;
exi t ( ) ;
}





ROCKEY6 SMART User Manual V1.3


145

Chapter 12 Advanced File System Application
12.1 Filter File
Filter file is a special executable file. Its name uses the reserved values of 7816-4. Therefore, the
difference between the filter file and the ordinary executable file can be recognized by their names.

J ust as the name indicates, filter file refers to a file with filtering functionality. It can filter some
specific information. In this case, the filtered information is information that the PC sends to the
ROCKEY6 SMART. It is also called APDU.

Filter file has the following special features:
If super password verification occurs before the operation, then all filter files are worthless.
The input buffer of the filter file can only start from 0. Namely, the first parameter of input
instruction is 0.

12.2 APDU
APDU stands for Applying Protocol for Data Unit. It is the fundamental data structure for
communication between the PC and IC card. Because ROCKEY6 SMART is a security product that is
based on the IC card, all layer communication between the PC and IC card are proceeded via data
switching. The API provided to developers is the interface of the APDU instruction package. If software
developers need to develop filter programs, then it is necessary to know when a read file command is
ROCKEY6 SMART User Manual V1.3


146
issued and what kind of data the IC card will receive. Here we will describe the APDU command
formats of the layer communication between ROCKEY6 SMART and the IC card.

APDUStructure
APDU can contain both command messages and response messages sent from the PC to the
card or vice versa. Both command messages and response messages can carry data, except for the
command message header.

APDUCommandMessage
APDU Command Messages are messages to the card from the computer. Their structure is:

Figure121APDUCommandMessageStructure

These items are described as follows:
Table121APDUImplicationsofCommandMessageItems
Categories Item Description
CLA(1byte) Instruction code
INS(1byte) Instruction categories
P1(1byte) Instruction parameter 1 (interpreted by the specific
instruction)
Command
Message
Header
(Required)
P2(1byte) Instruction parameter 2 (interpreted by the specific
instruction)
Lc(1byte) The length of data field (the length of data field after the
Lc is variable)
Others
Data field Data content
CLA INS P1 P2 Lc
Data field
Le
ROCKEY6 SMART User Manual V1.3


147
Le(1byte) Expected max length of data field in response message
(It is also the expected return data length)

APDUResponseMessage
This is the message to the computer from the card. Its structure is:


Figure122APDUResponseMessageStructure

SW1 and SW2 are the command message tails that must be present. If an error occurs in the IC
card, the error code is returned through those two bytes.

Data field is actually the return data from the IC card to the PC. If the return data length is uncertain,
then a response message is sent to the PC about the return data length. After that, the data message
will be sent.

12.3 ROCKEY6 SMART APDU Command Set
The ROCKEY6 SMART APDU command message structures are introduced below. They are the
foundations for writing filter programs.
1.CreateFile
CLA = 0x00
I NS = 0xE0
P1 = 0 Cr eat e vol ume
= 1 Cr eat e di r ect or y or f i l e
P2 = I f p1 i s 0 ( cr eat e vol ume) , i t i ndi cat es ATR f i l e l engt h ( max. 15) ;
Data field SW2 SW1
ROCKEY6 SMART User Manual V1.3


148
not used ot her wi se.
LC = t he l engt h of dat a f i el d
( assume t hese dat a i s st or ed i n a Buf f er wi t h BYTE t ype) .

Descriptions of the data in data field:
(1)WhenP1=0(Createvolume)
Buf f er [ 0] - Buf f er [ 15] : Vol ume name
Buf f er [ 16] - Buf f er [ 30] : ATR dat a
Note:
- The volume must have a name.
- The volume can only be created by the software developer. The end user is not authorized to
create it.
- When creating a volume, the COS will remove the remote update password and update tag.
(2)WhenP1=1(createdirectoryorfile)
Buf f er [ 0] - Buf f er [ 1] : Fi l e I D number , one WORD, l ow byt e pr ecedence
Buf f er [ 2] : Fi l e cl ass
Buf f er [ 3] : Fi l e at t r i but e
Buf f er [ 4] - Buf f er [ 5] : Fi l e l engt h, one WORD, l ow byt e pr ecedence
Buf f er [ 6] - Buf f er [ 22] : Opt i onal l ong f i l e name
Note:
- Long file name is optional, if it is not necessary, then clear Buffer[6] - Buffer[23].
- Super password verification is required to create an executable file.




ROCKEY6 SMART User Manual V1.3


149
2.SelectFile
CLA = 0x00
I NS = 0xA4
P1 = 0 ( Sear ch f i l e by I D)
= 1 ( Sear ch f i l e by name)
= 2 ( Di r ect l y sel ect t he upper di r ect or y)
P2 = Not used
LC = l engt h of dat a i n dat a f i el d
( Assume t hi s dat a i s st or ed i n a buf f er wi t h BYTE t ype)

Description of data in data field:
(1)WhenP1=0(SearchfilesbytheirIDs)
Buf f er [ 0] - Buf f er [ 1] : Fi l e I D number , one WORD, l ow byt e pr ecedence

(2)WhenP1=1(Searchfilebyname)
Buf f er [ 0] - Buf f er [ 15] : Fi l e name

(3)WhenP1=2(Directlyselecttheupperdirectory)
No dat a f i el d

3.BinaryRead
CLA = 0x00
I NS = 0xB0
P1 = shi f t hi gh byt e
P2 = shi f t l ow byt e
LC = buf f er l engt h ( byt e number of dat a t o be r ead i n)
ROCKEY6 SMART User Manual V1.3


150
No data field, but there should be a buffer to store the data to be read.

Note:
Every time the length of data to be read should not exceed 250 bytes.

4.BinaryWrite
CLA = 0x00
I NS = 0xD0
P1 = shi f t hi gh byt e
P2 = shi f t l ow byt e
LC = byt e number of t he f i l e t o be wr i t t en
The data in data field is the content to be written into the file

Note:
The maximum data length that APDU can write is 128 bytes. For data of more than 128 bytes, the
data has to be broken into 128 bytes blocks.

5.GetRandomNumber
CLA = 0x00
I NS = 0x84
P1 = Not used
P2 = Not used
LC = expect ed byt e number of r andomnumber ( cur r ent l y 6 byt es max)
No dat a f i el d.

6.ReadCurrentDirectoryRecord(listdirectory)
ROCKEY6 SMART User Manual V1.3


151
CLA = 0x00
I NS = 0xB2
P1 = r ecor d number ( number of sel ect ed di r ect or y)
P2 = Not used
LC = Buf f er l engt h ( must be 24 byt es)

There is a 22-byte buffer attached.
- Buffer[0] - Buffer[5]: for 6-byte file description input
- Buffer[6] - Buffer[21]: for 16-byte file name input (Clear in case of no file name)

7.DeleteFile
CLA = 0x00
I NS = 0xEE
P1 = 0 ( del et e cur r ent di r ect or y; 1, del et e cur r ent f i l e)
P2 = Not used
LC = 0
Get Cur r ent Di r ect or y / Fi l e
CLA = 0x00
I NS = 0x18
P1 = 0, get cur r ent di r ect or y;
I f 1, get cur r ent f i l e; i f 2, get t he upper di r ect or y
P2 = Not used
LC = Ret ur ned dat a byt e number f r omdongl e, must be 22

Returned data:
- Buffer[0] - Buffer[5]: for 6-byte file description input
ROCKEY6 SMART User Manual V1.3


152
- Buffer[6] - Buffer[21]: for 16-byte file name input (Clear in case of no file name)
12.4 Filter APDU
FilterFileNaming
All the commands described in Section 12.3 can be used as filter file names. The 2-byte CLA.INS
can be converted to a 4-byte file name, where the 4 high bits and the 4 low bits of every byte are
converted into one byte respectively. Therefore, each byte of the file name to be discussed is a
hexadecimal numeral. Another difference between the filter file name and the common executable files
is that the filter file can use long file name. Its convention is:

CLA.INS. [C class ID/F file ID]
The dot in the middle is to distinguish each part of the file name and it has no affect. Items in the
square brackets are optional, that is, the long file name may contain either its file class or ID.

Take executable file 00B0 as an example. When the system receives CLA.INS 00B0 of the APDU
command, it calls executable file 00B0, which filters the read file operation.

00B0CFE implies that, when the system receives CLA.INS 00B0 and the data file to be accessed
is of FE class, the executable file is called.

00B0F3002 indicates that, when the system receives CLA.INS 00B0 and the data file ID is 3002,
the executable file is called.

Multiple Filter Files
Before discussing multiple filter file applications, it is necessary to review the return function of the
executable programs. Normally, a program returns with exit. Its second parameter indicates whether
ROCKEY6 SMART User Manual V1.3


153
there is returned data. If the parameter is 0x61, COS will return the data directly to the host computer
when the program exits. If it is 0x90, no data is to be returned and the COS will not return any data to
the host computer.
If there are several filter files, when receiving an APDU, COS would execute the APDU in batch in
the following order: (XX is file category, yyyy is file ID)

Figure123ExecutionDiagramofMultipleFilterFiles

(2) Executes the APDU in the same way as (1), only names of the executable files are different.
The COS checks whether the executable file CLA.INS.CXX exists. If not, jump to the next step;
Does executable file
CLA.INS exist?
CLA.INS returns a
value?
Pass all APDU data to file CLA.INS
N
Next
N
Y
Return
Y
ROCKEY6 SMART User Manual V1.3


154
otherwise, transfer the APDU to the file, and check its return function parameter. J ust in case there is
data to be returned to the host computer, execute the return operation, and if not, jump to the next step.
After the 3rd step, if the program does not exit, COS will execute the corresponding instruction
according to CLA.INS.

The above are all the operations when COS receives an APDU. After the completion of every step,
it will transfer APDU to the next step. And in case that any error occurs in any of the chained programs
or there is data returned to the host computer, COS will terminate the program. When transferring data
to filter files, the COS places the entire APDU in the filter file input buffer (corresponding to the input
instructions of LC programs), instead of merely delivering the data to the filter file. This is different from
dealing with other executable files.

Filter Read File Sample
In previous chapters, we mentioned that the COS interprets all information (APDU) to ROCKEY6
SMART from the host computer and then executes the interpreted commands. For example, API sends
to ROCKEY6 SMART a command for reading file in the following codes. Assume that the file with ID
0x0002 is a common data file.
DI C_Set ( dat a, FI LE_I D, BY_VALUE, 0x0002, NULL) ;
er r code = DI C_Command( 0, SET_CURRENT_FI LE, dat a) ;

/ / r ead t he f i l e and di spl ay t he f i l e l engt h and cont ent
DI C_Set ( dat a, READ_DATA, 10, BY_VALUE| 0, NULL) ;
er r code = DI C_Command( 0, READ_FI LE, dat a) ;
r eadsi ze = DI C_Get ( dat a, READED_DATA, BY_VALUE, buf f er ) ;

Line 4 and 5 set two the input data before read file is executed: 10 is the data length to be read and
0 is the shift value. Referring to Section 4.3.3, you will find the host computer sends 3 APDU to
ROCKEY6 SMART User Manual V1.3


155
ROCKEY6 SMART: 0x00B0, 0x0000, 0x0A, in total 5 bytes.

When receiving the APDU the COS first checks if executable file 0x00B0 exists. If it exists, the
APDU is transferred to executable file 0x00B0 as a string, and then the executable file runs. If the file
0x00B0 does not exist, the COS will read the 10 bytes of data from the file 0x0002 and return it to the
host computer. If the executable file 0x00B0 does exist, it filters the command message of the APDU. It
is up to the programmer to define how to process the command message in the program, such as to
open a data file with ID 0x0020 and get 10 bytes of data starting from byte No.10 and then return. The
read data can be encrypted before it is returned to the host computer. The host computer in return
decrypts such data.

For example, in ROCKEY6 SMART, there is an executable file named 00B0F0002:
wor d i ;
wor d f i l eI D;
byt e xdat a be[ 50] ;
f i l eI D=0x3300;
open_f i l e( &f i l eI D, 0) ;
r ead_f i l e( 0, be, 20) ;
f or ( i =0; i <20; i ++)
{
be[ i ] +=1;
}
set _r esponse( 20, be) ;
exi t ( ) ;

This filter file filters the reading operation to the data file with ID 0033. The COS transfers the 5
bytes of APDU to the filter file. Then the data file with ID 0002 is read with the same shift and access
ROCKEY6 SMART User Manual V1.3


156
byte number, and every byte accessed is added with 1, and then returned. Of course, it can make other
operations to the command message. If the filter file is available in ROCKEY6 SMART, we can view the
filtered output by double clicking the file with ID 0002 in IDE, which is different from the content in the
original file. After super password verification, all the filter files will be disabled; the display is the original
content of the data file.

Filter List Directory
The APDU to read the current directory is 00B2. If it is necessary to prevent the unauthorized
person to view the contents of the dongle, you may filter the list directory to return an error code if the
list directory is attempted. The following code will return the error code 0x6982:
voi d mai n( )
{
wor d sw = 0x6982;
set _r esponse( 2, &sw) ;
exi t ( ) ;
}

Save the file in dongle under the name 00B2. Without the super password, opening a dongle wil
return an error message; it is a prompted internal error.
The name can be changed to 00B2FYYYY in order to protect a specific directory.

Filter Select File
The APDU to select file is 00A4. It is necessary to select file(s) before to read/write/delete files.
Therefore, filtering file selection can perform the overall protection of files. In addition, filtering directory
file can protect all the files under the directory. If the conditions are not met, it is not possible to list
directories.

ROCKEY6 SMART User Manual V1.3


157
Filter Write File
It is not necessary to require super password verification for writing non-executable files. If there
are some important data files and certificates in the dongle and they are not internal files, you can have
the files write protected. For example, to protect data files with Class 0x32 or ID 0x7022 against any
unauthorized write and only you yourself can write properly. You may design in this way: filter the file
write command, the first 8 bytes of the data from the APDU are treated as the file password. First check
for the file password, if incorrect, file write is rejected; if correct, write the data after the 8-byte password
to the file. In this case, the maximum length of data to be written is 120 bytes. Following is the example
code:
voi d mai n( )
{
byt e xdat a par a[ 41] , l engt h = 41, i ;
wor d f i l eI D;
byt e key[ 8] ;
get _i nput ( par a, 0, 0, 41) ;

/ / Def aul t passwor ds
key[ 0] =0x30;
key[ 1] =0x31;
key[ 2] =0x32;
key[ 3] =0x33;
key[ 4] =0x34;
key[ 5] =0x35;
key[ 6] =0x36;
key[ 7] =0x37;
/ / Check i f t he passwor d i s cor r ect
f or ( i =0; i <8; i ++) {
ROCKEY6 SMART User Manual V1.3


158
i f ( key[ i ] ! =par a[ i ] )
{
exi t ( ) ; / / I ncor r ect passwor d, qui t
}
}
f i l eI D= 0x0005;
i = open_f i l e( &f i l eI D, 0) ;
i f ( i ==0x05)
{
cr eat _f i l e( f i l eI D, NULL, 0, 0x2500) ;
open_f i l e( &f i l eI D, 0) ;
}
wr i t e_f i l e( 0x0000, par a+8, 33) ;
exi t ( ) ;
}

Naming the file as 00D0F0005 after compilation, this indicates to proceed filtering once writing to
file with ID 0x0005. It will avoid any unauthorized writing to this sensitive file.







ROCKEY6 SMART User Manual V1.3


159

Chapter 13 COS System Call Reference
The following is all the system call functions descriptions:
13.1 File Operations
File operations can operate the files and directories in the EEPROM.
create_file
Function Create file/directories
Syntax
byte creat_file(IN word wFileID, IN byte pbFileName, IN byte bAttrib,
IN word wSize)
wFileID File/Directory ID
pbFileName


File/directory name buffer area (file name is in 16
bytes maximum. If there is no file name, then the first
letter of the buffer should be clear to 0 or set to NULL
pointer), such as aaa.
bAttrib File/Directory attributes and security levels
Parameter
wSize File length (counted in bytes, if it is directory,
parameter is 0; low byte is at the left part, and high
byte is at right part.)
Return Return code, please see also CC

The file ID can be represented by a word type variable as the parameter; it is not necessary to be a
number. Please note the file / directory class is the same with that of the executable file. If a file is
ROCKEY6 SMART User Manual V1.3


160
created, it is selected by default upon completion, and it is ready for read, write, or delete operations. If
a directory is created, use OpenFile() to open the directory before entering it.
Following is the detailed description for each parameter.
ID:File/DirectoryID
When creating file in the root directory, 0000 (system reserved), 2F01 (ATR file, including
manufacturer information), 3F00 (volume) and 3FFF (current directory) cannot be used. When creating
file or directory in any sub-directory, please do not use 3FFF, because this ID represents the current
directory.
abbr: file / directory attributes and security levels

The high part of this type represents the file / directory attributes. Following is their description:
Attributes Label Description
Normal file 0x00 Not any special attributes
Executable
file
0x10 The file is executable, but it can only be created by the
main program, no other programs in the dongle.
Directory 0x20 Create a directory
Upignore 0x40 It only works for the executable files. If it can work, it means
the security levels of the executable file must be higher
than the system security levels. In other words, if the
security levels of the executable file is less than or equal to
the system security levels, then the executable file cannot
be executed.
Internal file 0x80 If it is a data file, then it represents that the data file can
only be accessed by the executable files in the dongle.
External operations can only delete it rather than read and
write after successful super password verification. Without
successful super password verification, it is impossible for
ROCKEY6 SMART User Manual V1.3


161
external programs to access the data file.
If it is executable file, then it means the executable file has
some hidden attributes. When all files are listed, if there is
no successful super password verification, all executable
files with the hidden attributes cannot be shown. It is an
important way to protect executable files.

The file security levels are represented via the low byte of the abbr. It contains 16 distinguished
authorization levels. The lowest level is 0, and the highest is 15.
COS has its own security levels.

delete_file
Function Delete opened file
Syntax byte delete_file()
Parameter None
Return Return code, please refer to 13.10
The internal operations are not provided with the interfaces for deleting directories. It can only be
performed externally or used with the provided API.

open_file
Function Open file/directory or return to upper level
Syntax byte open_file (IN byte *pd, IN byte open_mode)
Parameter pd The pointers for the file names or file IDs.
ROCKEY6 SMART User Manual V1.3


162
open_mode Open method
00 Sort in file/directoy ID, (pointer is pointing to file/directory
ID, the lower byte is in the front).
01 Sort in file/directory name (at this time, the pointer is
pointed to file/directory names)
02 directly open the upper directory. At this time, pd is
NULL or other values; however, its value would be
neglected.
Return Return code, please refer to 13.10
If the directory names or IDs were being transferred, then they would enter the sub directory.

write_file
Function Write data into the file
Syntax byte write_file(IN word offset, IN byte *pd, IN word length)
offset The shifting positions for the file data to be written in.
pd Pointer buffer, the initial address for the source data.
Parameter
lenth The number of total bytes to be written in.
Return Return code, please refer to 13.10

read_file
Function Reading file
Syntax byte read_file(IN word offset, OUT byte *pd, IN word length)
offset The shifting positions of the file data to be read.
pd Pointer, points the address that stores the data.
Parameter
lenth The number of the total bytes to be read.
Return Return code, please refer to 13.10
ROCKEY6 SMART User Manual V1.3


163
Note:
There is no close file operation to be displayed. Once the application program opens a new file,
or the application program finished its execution, the previous opened file will be closed automatically.

13.2 Security Mechanism
set_class
Function Changing the COS security state level.
Syntax byte set_class(IN byte value)
Parameter value Assigned security state level. (It could be 0x00-0x0f or
0xff. If the parameter is 0xff, the COS security level
would change to the same security state level with the
function set_class.)
Return Return code, please refer to 13.10
Note:
Because the security level is related to the file class, when the COS security level changes, current
system file class will change to the executable class accordingly. To execute it properly, the executable
file level must be higher than or equal to the security level of set_class function.

get_class
Function Get the current system security level
Syntax byte get_class(OUT byte * pd)
Parameter Pd address, points to the return value.
pd[0] The current system file class
Pd[1] The current system security level
ROCKEY6 SMART User Manual V1.3


164
Pd[2] Application program security level
Return Return code, please refer to 13.10

get_Status
Function Get system external verification state
Syntax byte get_status(IN byte *pd)
Parameter Pd address, points to the return value
Return code, please refer to 13.10 Return
There are three return values for the current system external verification
state:
0 Non-verified password state
4 Super password verification state
8 Remote update password verification state

13.3 System Services
exit
Function Stop execution and return to the main program.
Syntax Exit()
Parameter None
Return None



ROCKEY6 SMART User Manual V1.3


165
sys_recall
Function Execution of self-terminated and call another application program.
Syntax byte sys_recall(IN byte value, IN byte *pd, IN word length, IN byte *pdnext);
value Additional operations for stopping the program:
* bit0 security level clear bit 0/1 maintain/clear the
application security level settings.
* bit1 RAM clear bit 0/1 maintain/clear the VM RAM
(after the data passed back to the host machine).
* bit2 used to choose the next file 0/1 using file
name/file ID to choose the next executable file.
The range of its values is 0-7.
pd Address, points to the ID of the program to be called.
length The length of the buffer (it will be passed to the next
application program)
Parameter
pdnext The buffer starting address (it will be passed to the next
application program)
Return None

set_response
Function
Return the response data to the caller, and using get_response function
to get the response data.
Syntax byte set_response(IN byte len, OUT byte *pd);
len The length of the return data Parameter
pd Address, points to the storage place for return data
Return None

ROCKEY6 SMART User Manual V1.3


166
get_input
Function Get the input parameter of the application program
Syntax byte get_input(IN byte* pd, IN byte offset, IN byte mode, IN byte number);
pd Address, points to the data address
offset The shifting in every parameters
mode mode=0, BYTE type data,
mode=1, WORD type data,
mode=2, DWORD type data
Parameter
number It represents the number of parameters with type
MODE.
Return Return code, please refer to 13.10
Note:
When MODE set to 1 or 2, the bytes are shifted inside COS. If we want to find a file with
ID=0x0057, then we would input file ID to 0x0057. It will be shifted to the left-part right once using
get_input (&ID, 0, 1, 1) . Inside the COS, we would then get the file with ID=0x0057. It will work
compatibly with the previous versions.

13.4 System Information
get_hard_infor
Function Get system hardware information
Syntax byte get_hard_infor(OUT byte *pd)
Parameter Pd Address, points to the return value.
pd[0..3] Manufacture time
ROCKEY6 SMART User Manual V1.3


167
pd[4..7] Hardware serial number
pd[7..11] Shipping time
pd[11..15] COS version
Return Return code, please refer to 13.10

get_sys_infor
Function Get system management information
Syntax byte get_sys_infor(OUT byte *pd)
Parameter pd address, points to the return value.
pd[0, 1] Zone code
pd[2, 3] Reseller code
Pd4, 5] User code 1
pd[6, 7] User code2
Return Return code, please refer to 13.10

get_file_infor
Function Get relevant information of current directory or file
Syntax byte get_file_infor(OUT byte *pd, IN byte mode)
pd Address, points to the return value
pd[0] FIle ID or directory ID
pd[1] File class or directory class
pd[2] File attributes and file security level or directory attributes
and directory security level.
Pd[3..4] File size or directory size
Parameter
Pd[5..21] File name or directory name
ROCKEY6 SMART User Manual V1.3


168
mode There are three values for choosing the directories or
files:
0 get current directory
1 get current file
2 get upper directory
Return Return code, please refer to 13.10
Here, the directory refers to the directory for holding the current executing program; the file refers
to the files that are operated by the executing program. If the executing program does not operate any
files, then the return information with parameter equals one and would be meaningless.

13.5 Double Precision Float Calculation
add,sub,multianddiv
Function
Calculating adding, subtracting, multiplying and dividing for double precision
float numbers.
Syntax
byte double_add(IN byte *a, IN byte*b, OUT byte *result);
byte double_sub(IN byte*a, IN byte*b, OUT byte*result);
byte double_mul(IN byte *a, IN byte*b, OUT byte *result);
byte double_div(IN byte*a, IN byte*b,OUT byte*result);
a Address, points to the first floating point number. It is the
number to be added / subtracted / multiplied / divided.
b Address, points to the second floating point number.
Parameter
result Address, points to a 8-byte buffer that is used for storing
the computation results.
ROCKEY6 SMART User Manual V1.3


169
Return Return code, please refer to 13.10
Once it is finished, the computation result would be stored in the default
memory area.

sqrt
Function The floating point number square root calculation
Syntax byte double_sqrt(IN byte *a, OUT byte *result);
a Address, points to a floating point number Parameter
result Address, points to a 8-byte buffer that is used for storing
the computation results.
Return Return code, please refer to 13.10
Once it is finished, the computation result would be stored in the default
memory area.

sinandcos
Function Calculating the value of sin and cos for float numbers.
Syntax
byte double_sin(IN byte *a, OUT byte *result)
byte double_cos(IN byte *a, OUT byte *result)
A Address, points to a floating point number, the number is
a radian value.
Parameter
result Address, points to an 8-byte buffer that is used for
storing the computation results.
Return Return code, please refer to 13.10
Once it is finished, the computation result will be stored in the default
memory area.

ROCKEY6 SMART User Manual V1.3


170
double2int
Function
Double precision float numbers converts to signed 32-byte integer, and will
take the integer part directly.
Syntax byte double2int(IN byte *a, OUT byte *result);
a Address, points to a floating point number. Parameter
result Address, points to a 4-byte buffer that is used for storing
the computation results.
Return Return code, please refer to 13.10
Once it is finished, the computation result would be stored in the default
memory area.

int2double
Function Signed 32-byte integer converts to double precision floating point number.
Syntax byte int2double(IN byte *a, OUT byte *result);
a Address, points to a signed 32-byte integer. Parameter
result Address, points to an 8-byte buffer that is used for
storing the computation results.
Return Return code, please refer to 13.10
Once it is finished, the computation result will be stored in the default
memory area.

abs
Function Absolute value for float point numbers
Syntax byte double_abs(IN byte *a, OUT byte *result);
Parameter a Address, points to a floating point number.
ROCKEY6 SMART User Manual V1.3


171
result Address, points to an 8-byte buffer that is used for
storing the computation results.
Return Return code, please refer to 13.10
Once it is finished, the computation result will be stored in the default
memory area.

compare
Function Comparing two float point numbers.
Syntax byte double_compare(IN byte *a, IN byte *b, OUT byte *result);
a Address, points to the first float point number.
b Address, points to the second float point number.
Parameter
result Address, points to a 1-byte buffer that is used for storing
computation results.
Return Return code, please refer to 13.10
Once it is finished, the computation result will be stored in the default
memory area.
There are three computation results: 0 (a ==b), 1 (a >b) and 1 (0xff) (a <b)

13.6 Float Point Library Expansion
asin
Function Calculating the value of asin
Syntax byte double_asin (IN byte *a, OUT byte *result)
Parameter a Address, points to a floating point number.
ROCKEY6 SMART User Manual V1.3


172
result Address, points to an 8-byte buffer that is used for storing the
computation results.
Return Return code; please refer to 13.10.
Once it is finished, the computation result will be stored in the default
memory area.

acos
Function Calculating the value of acos
Syntax byte double_acos(IN byte *a, OUT byte *result)
Parameter a Address, points to a floating point number.
result Address, points to an 8-byte buffer that is used for storing the
computation results.
Return Return code, please refer to 13.10
Once it is finished, the computation result will be stored in the default
memory area.

atan
Function Calculating the value of atan
Syntax byte double_atan(IN byte *a, OUT byte *result)
Parameter a Address, points to a floating point number.
result Address, points to an 8-byte buffer that is used for storing the
computation results.
Return Return code, please refer to 13.10
Once it is finished, the computation result will be stored in the default
memory area.

ROCKEY6 SMART User Manual V1.3


173
sinh
Function Calculating the value of sinh.
Syntax byte double_sinh(IN byte *a, OUT byte *result)
Parameter a Address, points to a floating point number.
result Address, points to an 8-byte buffer that is used for storing the
computation results.
Return Return code, please refer to 13.10
Once it is finished, the computation result will be stored in the default
memory area.

cosh
Function Calculating the value of cosh.
Syntax byte double_cosh(IN byte *a, OUT byte *result)
Parameter a Address, points to a floating point number.
result Address, points to an 8-byte buffer that is used for storing the
computation results.
Return Return code, please refer to 13.10
Once it is finished, the computation result will be stored in the default
memory area.

tanh
Function Calculating the value of tanh
Syntax byte double_tanh(IN byte *a, OUT byte *result)
Parameter a Address, points to a floating point number.
ROCKEY6 SMART User Manual V1.3


174
result Address, points to an 8-byte buffer that is used for storing the
computation results.
Return Return code, please refer to 13.10
Once it is finished, the computation result will be stored in the default
memory area.

ceil
Function Calculating the minimum integer greater than double.
Syntax byte double_ceil(IN byte *a, OUT byte *result)
Parameter a Address, points to a floating point number.
result Address, points to an 8-byte buffer that is used for storing the
computation results.
Return Return code, please refer to 13.10
Once it is finished, the computation result will be stored in the default
memory area.


floor
Function Calculating the maximum integer less than the double.
Syntax byte double_floor(IN byte *a, OUT byte *result)
Parameter a Address, points to a floating point number.
result Address, points to an 8-byte buffer that is used for storing the
computation results.
Return Return code, please refer to 13.10
Once it is finished, the computation result will be stored in the default
memory area.
ROCKEY6 SMART User Manual V1.3


175

exp
Function Calculating exp. function
Syntax byte double_exp(IN byte *a, OUT byte *result)
Parameter a Address, points to a floating point number.
result Address, points to an 8-byte buffer that is used for storing the
computation results.
Return Return code, please refer to 13.10
Once it is finished, the computation result will be stored in the default
memory area.

log
Function Calculating log function
Syntax byte double_log(IN byte *a, OUT byte *result)
Parameter a Address, points to a floating point number.
result Address, points to an 8-byte buffer that is used for storing the
computation results.
Return Return code, please refer to 13.10
Once it is finished, the computation result will be stored in the default
memory area.

log10
Function Calculating the value of log10
Syntax byte double_log10(IN byte *a, OUT byte *result)
Parameter a Address, points to a floating point number.
ROCKEY6 SMART User Manual V1.3


176
result Address, points to an 8-byte buffer that is used for storing the
computation results.
Return Return code, please refer to 13.10
Once it is finished, the computation result will be stored in the default
memory area.

fmod
Function Calculating the mod of two double precision floating-point numbers.
Syntax byte double_fmod(IN byte *a, double b, OUT byte *result)
a Address, points to a floating point number. Parameter
b Address, points to two float numbers.
result Address, points to an 8-byte buffer that is used for storing the
computation results.
Return Return code, please refer to 13.10
Once it is finished, the computation result will be stored in the default
memory area.

13.7 Encryption and Decryption Functions
des_enc
Function des ECB encryption
Syntax
byte des_enc(IN word fileID, IN byte keyID, IN word length, IN OUT void
*data)
Parameter fileID The ID of the file that is used for storing the key
ROCKEY6 SMART User Manual V1.3


177
keyID Storing the key ID; it is prohibited to store more than 256 keys in a
data file.
length The length of input data
data Data address, used to store input data and return data.
Return Return code, please refer to 13.10
Once it is finished, the computation result will be stored in the default
memory area.

des_dec
Function des ECB decryption
Syntax
byte des_dec(IN word fileID, IN byte keyID, IN word length, IN OUT void
*data)
fileID The ID of the data file that is used for storing keys.
keyID Storing the key ID; it is prohibited to store more than 256 keys in a
data file.
length The length of input data
Parameter
data data address, used to store input data and return data.
Return Return code, please refer to 13.10
Once it is finished, the computation result will be stored in the default
memory area.

tdes_enc
Function 3des ECB encryption
Syntax
byte tdes_enc(IN word fileID, IN byte keyID, IN word length, IN OUT void
*data)
Parameter fileID The ID of the data file that is used for storing keys.
ROCKEY6 SMART User Manual V1.3


178
keyID Storing the key ID; it is prohibited to store more than 256 keys in a
data file.
length The length of input data
data data address, used to store input data and return data.
Return Return code, please refer to 13.10
Once it is finished, the computation result will be stored in the default
memory area.

tdes_dec
Function 3des ECB decryption
Syntax
byte tdes_dec(IN word fileID, IN byte keyID, IN word length, IN OUT void
*data)
fileID The ID of the data file that is used for storing the keys
keyID Storing the key ID; it is prohibited to store more than 256 keys in a
data file.
length The length of input data
Parameter
data data address, used to store input data and return data.
Return Return code, please refer to 13.10
Once it is finished, the computation result would be stored in the default
memory area.

rsa_gen_key
Function Generating key pairs
Syntax byte rsa_gen_key (word pubKey, word KeyLen, word PriKey)
Parameter pubKey The public key file ID
Parameter KeyLen The length of key space
ROCKEY6 SMART User Manual V1.3


179
Parameter PriKey The private key file ID
Return Return code, please refer to 13.10
Once it is finished, the computation result would be stored in the default
memory area.

rsa_enc
Function RSA encryption, the value of e is 65537.
Syntax byte rsa_enc(IN word fileID, IN word length, IN OUT void *data)
fileID The ID of RSA public key.
length The length of input data
Parameter
data data address, used to store input data and return data.
Return Return code, please refer to 13.10
Once it is finished, the computation result will be stored in the default
memory area.

rsa_dec
Function RSA decryption, the value of e is 65537.
Syntax byte des_dec (IN word fileID, IN word length, IN OUT void *data)
fileID The ID of RSA private key.
length The length of input data
Parameter
data data address, used to store input data and return data.
Return Return code, please refer to 13.10
Once it is finished, the computation result will be stored in the default
memory area.

ROCKEY6 SMART User Manual V1.3


180
13.8 Timer and Counter
get_timer
Function Get the execution time once the dongle is activated.
Syntax byte get_timer (OUT dword *timer)
Parameter Return the address of the data; its unit is microsecond.
Return Return code, please refer to 13.10
Once it is finished, the computation result will be stored in the default
memory area.

start_timer
Function Starting timer
Syntax byte start_timer ()
Parameter None
Return Return code, please refer to 13.10

step_counter()
Function Counter minus 1.
Syntax byte step_counter()
Parameter None
Return Return code, please refer to 13.10

get_counter()
Function Get the times of the counter
Syntax byte get_counter(byte *counter)
ROCKEY6 SMART User Manual V1.3


181
Parameter counter address of the counter
Return Return code, please refer to 13.10

set_counter()
Function set the times of the counter.
Syntax byte step_counter()
Parameter None
Return Return code, please refer to 13.10

13.9 Others
get_rand
Function Get random number
Syntax byte get_rand(byte *pd, byte len)
Pd Buffer pointer, is used for storing returned random number. Parameter
len Assigned length of random number (counted in byte)
Return Return code, please refer to 13.10
Once it is finished, the computation result will be stored in the default
memory area.
The parameter can be a variable (either in byte type or in word type). Or it can simply use digits.

Note:
It can assign any values to memory [0], but only 16 bytes would be return by the system. Thus, if
more than a16-byte value is given, then the system can only return a random number in 16-bytes.
There is no error message prompting.
ROCKEY6 SMART User Manual V1.3


182

get_remote_tag
Function Getting remote update tag
Syntax byte get_remote_tag (OUT dword *Tag)
Parameter Tag Remote update tag
Return Return code, please refer to 13.10
Once it is finished, the computation result will be stored in the default
memory area.

13.10 System Function Call Error Code
Systemcallerrorcodes
Return value Description
0 Application program is correctly terminated.
1 Invalid file
2 The file already exists.
3 Insufficient memory space
4 Security requirement is not sufficient
5 File is not found
6 Memory operation error
7 Data error
8 Invalid parameter
9 Virtual machine overflow


ROCKEY6 SMART User Manual V1.3


183
Appendix
Appendix A Glossary of Terms
A1. Main program
The main program is the part of the software running on the host computer. It has complete control
over software operation.
A2. Protected program
The protected program refers to the part of the program that only runs inside the dongle. A
program could run many of its sub programs inside the dongle. But only one protected program is
activated each time. A protected program is a function independent program. That means the protected
program has its own inputs and outputs corresponding to the encryption points in the main program.
A3. Protected execution
Protected execution always follows the protected compile. It would fetch the program in the virtual
card or real card.
ROCKEY6 SMART User Manual V1.3


184
A4. Executable file
Executable file refers to the binary code existing in the dongle after external program compiling. It
can be executed inside the card.
ROCKEY6 SMART User Manual V1.3


185
Appendix B TERMS
B1 The Common Errors in the C51 Program
(1) Please make sure the correct parameter type settings are used during the system call because
KEIL never checks the parameter types. For example:
voi d mai n( )
{
shor t f i l ei d ;
open_f i l e( f i l ei d, 0) ; / / i ncor r ect
open_f i l e( &f i l ei d, 0) ; / / cor r ect , kei l does not r epor t er r or i n compi l i ng
}

(2) The created file should be compatible with its previous version. Reversed creating file ID and
the file size (low byte is located at left and high byte is at right). Following is an example:
voi d mai n( )
{
shor t f i l eI D = 0x0a3f / / The nor mal or der i s 0x3f 0a.
char i nf o[ 100] ;
get _i nput ( i nf o, 100) ;
i s = open_f i l e( &f i l eI D, 0) ;
i f ( i s! =0)
{
cr eat _f i l e( f i l eI D, " ef Fi l e" , 0x00, 0x6400) ; / / Cr eat e a nor mal dat a f i l e
}
ROCKEY6 SMART User Manual V1.3


186
wr i t e_f i l e( 0, i nf o, 100) ; / / Wr i t e f i l e.
r ead_f i l e( 80, r esul t , 20) ; / / Read f i l e, excur si on i s 80 and r ead 20 byt es.
}

(3) When using get_input() function and the data mod is 1 or 2 (choosing the data type in short or
int), the byte in the COS are reversed. Especially in selecting file ID case, the sample13 program inputs
file ID=0x5700. This is actually the program accessing the ID=0x0057 file.

(4) Another problem is about the DIC_Get() function. In sample11, when the COS result is
0x0019, we get c =DIC_Get (buffer, 1, BY_VALUE |1, NULL); //get c from the running result.
Please pay attention to DIC_Get parameters. In most cases, the error is caused from the incorrect
byte sequence.

(5) Due to some bugs in the Keil compiler, when you try to compile dword dNum=255*255 the
compiler will generate 0xfffffe01.

(6) String initialization problem. Cannot directly set value to a pointer, such as: char *p=str;
should be replaced as char p[]=str .




B2 ROCKEY6 SMART Developers Kit
The user will find the ROCKEY6 SMART Developers Kit in the ROCKEY6 SMART installation disc.
ROCKEY6 SMART User Manual V1.3


187
The following table contains the general information for the ROCKEY6 SMART Developers Kit
(setup.exe is omitted):
Index Description
API32 ROCKEY6 SMART Development Kits, applying to all Windows OS
API64 ROCKEY6 SMART Development Kits for 64-bit OS
Include ROCKEY6 SMART Header Files
Docs ROCKEY6 SMART User Manual
Driver for Win98 USB MASS STORAGE Driver for Win98
Linux ROCKEY6 SMART SDK for Linux
Samples ROCKEY6 SMART Samples for Types of Development Environments
Support Third-Party Development Tools, assisting customer in the
development of C51 projects
Tools ROCKEY6 SMART Common Tools
Double2Byte Tools for Introversion Between Binary and Floating Point Number
ErrorLookup Tools for Error Lookup
IDEII ROCKEY6 SMART Integrated Environment
RemoteUpdate ROCKEY6 SMART Remote Update Tool

KeilWizard Rockey6Smart Keil Project Wizard