Scribd
Upload
120 views5 pages

ROCKEY2 Dongle Developer Guide

The document is a developer's guide for the ROCKEY2 software protection dongle. It includes 5 chapters that describe: 1) a brief introduction to ROCKEY2, 2) its features which include read/write memory and support for multiple dongles, 3) the ROCKEY2 API for functions like finding, opening, reading and writing dongles, 4) error codes for API functions, and 5) low-level technical details for using ROCKEY2 as a USB device.

Uploaded by

tester zack
Copyright
© All Rights Reserved
We take content rights seriously. If you suspect this is your content, claim it here.
Available Formats
Download as PDF, TXT or read online on Scribd
120 views5 pages

ROCKEY2 Dongle Developer Guide

The document is a developer's guide for the ROCKEY2 software protection dongle. It includes 5 chapters that describe: 1) a brief introduction to ROCKEY2, 2) its features which include read/write memory and support for multiple dongles, 3) the ROCKEY2 API for functions like finding, opening, reading and writing dongles, 4) error codes for API functions, and 5) low-level technical details for using ROCKEY2 as a USB device.

Uploaded by

tester zack
Copyright
© All Rights Reserved
We take content rights seriously. If you suspect this is your content, claim it here.
Available Formats
Download as PDF, TXT or read online on Scribd

ROCKEY2 Software Developer’s Guide

Table of Contents

Chapter1 Brief Introduction.................................................... 1


Chapter 2 ROCKEY2 Features............................................... 1
Chapter 3 ROCKEY2 API ....................................................... 2
Chapter 4 Error Codes............................................................. 3

i
ROCKEY2 Software Developer’s Guide

Chapter1 Brief Introduction


ROCKEY2 is a traditional secure storage dongle that is extremely simple to implement and low
cost. It does not offer many of the advanced software protection methods available in ROCKEY4
or ROCKEY5.

The Features of ROCKEY2 include:

ROCKEY2 has 2560 bytes of Read/Write memory spaces ,which is much bigger than most of
other software protection dongles.
ROCKEY2 is an HID device so there is no driver required for supported Linux or Windows
platforms.
Each ROCKEY2 has a globally unique hardware ID.
Multiple ROCKEY2s can work together on the same computer.
ROCKEY2 supports USB only.

Chapter 2 ROCKEY2 Features


User ID (UID) and Hardware ID (HID)

Each ROCKEY2 dongle contains a User ID (UID) as well as the globally unique Hardware ID
(HID). Both the UID and HID are defined as 32-bit DWORD. The UID and HID are identifiers for
the ROCKEY2 dongle.

The default UID is “0”. While the UID remains at default you may open and read/write to the
dongle memory. But you cannot obtain the HID. The HID is shielded while the UID is set to the
default. The shielded HID will return a value of “0”. The correct HID may be obtained only after
the developer resets the UID.

When generating the UID, a 64 bytes string is required as seed code. The UID will be derived
from this seed code. The UID generation is performed within the dongle hardware. The process is
absolutely irreversible, which means only the user generated the UID knows which seed code is
his UID derived from. Even hacker knows UID and knows how to use UID generating program,
as he do not know the seed code, he can not reproduce the dongle with the same UID.

Additionally, software vendor can determine whether the store zone is writable or not when
generating the UID. If the dongle is set to unwritable, the entire memory zone will be written
protected.

ROCKEY2 Driver

The ROCKEY2 dongle is a USB device that uses the driver native to the Windows and Linux
operating systems. When the dongle is inserted into the USB port, the operating system will
prompt you for installing the new device. With Windows 98 you may need the Win98 installation
CD-ROM. You will not need a CD-ROM or other storage media for Win Me/2000/XP – the driver
will install automatically.

The operating system combines the UID and HID to identify the dongle and install its driver.
When a dongle is first plugged into the computer, you will need to go through the driver
installation process. When you reset the UID, the computer will see it as a new device and you
will have to go through the process again. Once the UID is set the computer will record the new

1
ROCKEY2 Software Developer’s Guide

UID/HID combination and you will not have to reinstall the driver. Keep in mind that since each
dongle has a unique HID, and the operating system will check the combination of UID and HID,
every new dongle inserted into the computer will require installation of its driver. However, once
the driver is installed for a specific UID/ HID combination, the dongle may be removed and
reinserted to the computer without reinstalling the driver.

Please note that the driver installation process is triggered by the dongle being inserted into the
computer. When you change the UID, please remove and reinsert the dongle to install the driver
for the new UID/HID combination.

ROCKEY2 is initially preformatted with UID=0 and the HID shielded so that HID=0. The
computer operating system will see these “out of the box” dongles as device “00”. You should
reset the UID so that the operating system can see a unique UID/HID combination. The UID needs
to be reset for multiple dongles to work together on the same computer. The UID should certainly
be reset before the dongle is re-shipped and the UID generation call should not be included in the
package sent to the end users.

Chapter 3 ROCKEY2 API


1. RY2_Find: Find ROCKEY2 dongles attached to the computer

EXTERN_C int WINAPI RY2_Find();


Return <0 Error code
Value =0 No ROCKEY2 dongle is attached
>0 The number of attached ROCKEY2 dongle(s)

2. RY2_Open: Open specified ROCKEY2 dongle

EXTERN_C int WINAPI RY2_Open(int mode, DWORD uid, DWORD* hid);


Input mode This parameter indicates the way to open the dongle
mode = 0, open the first found ROCKEY2 dongle
mode > 0, open the dongle according to the UID. The mode value is the
dongle number, for example: uid=12345678, mode=2, this means it will
open the second dongle with UID 12345678
mode = -1, open the dongle according to the HID, and *hid can not be 0
We defined two MACROs: AUTO_MODE=0 and HID_MODE=-1
uid(User ID) You need to specify the dongle UID and this UID is generated with
RY2_GenUID
hid(Hardware Open dongle with HID of *hid
ID) The dongle HID will be returned to *hid regardless of how the dongle
was opened.
Return >=0 Success. The opened dongle handle is returned.
<0 Error code. Please refer to the Chapter 4 Error Codes

3. RY2_Close: Close specified ROCKEY2 dongle

EXTERN_C int WINAPI RY2_Close(int handle);


Input ROCKEY2 dongle handle. It is the handle returned from RY2_Open
Return Error code. Please refer to the Chapter 4 Error Codes

2
ROCKEY2 Software Developer’s Guide

4. RY2_GenUID: Generate User ID(UID)

EXTERN_C int WINAPI RY2_GenUID(int handle, DWORD* uid, char* seed, int isProtect)
Input Handle Dongle handle. It is the handle returned from RY2_Open
Uid Output parameter. The generated UID
Seed Seed to generate UID. It is a character string with the maximum
length of 64 bytes
isProtect Sets write protection. 0=dongle not write protected, 1=dongle write
protected.
We defines two MACROs:
#define ROCKEY2_DISABLE_WRITE_PROTECT 0
#define ROCKEY2_ENSABLE_WRITE_PROTECT 1
Return Error code. Please refer to Chapter 4 Error Codes

5. RY2_Read: Read dongle content

EXTERN_C int WINAPI RY2_Read(int handle, int block_index, char* buffer512);


Input handle Dongle handle. It is the handle returned from RY2_Open
block_index Block index. Specify the block to read. The value range is 0-4
buffer512 Read buffer. The buffer must be at least 512 bytes to accommodate
the 512 byte block size.
Return Error code. Please refer to Chapter 4 Error Codes

6. RY2_Write: Write to ROCKEY2 dongle

EXTERN_C int WINAPI RY2_Write(int handle, int block_index, char* buffer512);


Input handle Dongle handle. It is the handle returned from RY2_Open
block_index Block index. Specify the block to write. The value range is 0-4
buffer512 Write buffer. The buffer must be at least 512 bytes to accommodate
the 512 byte block size.
Return Error code. Please refer to Chapter 4 Error Codes

Chapter 4 Error Codes


MACRO Value Description
RY2ERR_SUCCESS 0 Success
RY2ERR_NO_SUCH_DEVICE 0xA0100001 Specified dongle is not found
(parameter error)
RY2ERR_NOT_OPENED_DEVICE 0xA0100002 Need to call RY2_Open first to
open the dongle, then call this
function (operation error)
RY2ERR_WRONG_UID 0xA0100003 Wrong UID(parameter error)
RY2ERR_WRONG_INDEX 0xA0100004 Block index error (parameter
error)
RY2ERR_TOO_LONG_SEED 0xA0100005 Seed character string is longer
than 64 bytes when calling
GenUID (parameter error)
RY2ERR_WRITE_PROTECT 0xA0100006 Tried to write to write-protected
dongle(operation error)

3
ROCKEY2 Software Developer’s Guide

RY2ERR_OPEN_DEVICE 0xA0100007 Open device error (Windows


error)
RY2ERR_READ_REPORT 0xA0100008 Read record error(Windows error)
RY2ERR_WRITE_REPORT 0xA0100009 Write record error(Windows error)
RY2ERR_SETUP_DI_GET_ 0xA010000A Internal error (Windows error)
DEVICE_INTERFACE_DETAIL
RY2ERR_GET_ATTRIBUTES 0xA010000B Internal error (Windows error)
RY2ERR_GET_PREPARSED_DATA 0xA010000C Internal error (Windows error)
RY2ERR_GETCAPS 0xA010000D Internal error (Windows error)
RY2ERR_FREE_PREPARSED_DATA 0xA010000E Internal error (Windows error)
RY2ERR_FLUSH_QUEUE 0xA010000F Internal error (Windows error)
RY2ERR_SETUP_DI_CLASS_DEVS 0xA0100010 Internal error (Windows error)
RY2ERR_GET_SERIAL 0xA0100011 Internal error (Windows error)
RY2ERR_GET_PRODUCT_STRING 0xA0100012 Internal error (Windows error)
RY2ERR_TOO_LONG_DEVICE_DETAIL 0xA0100013 Internal error
RY2ERR_WRONG_REPORT_LENGTH 0xA0100020 Unknown device(hardware error)
RY2ERR_VERIFY 0xA0100021 Verification error(hardware error)
RY2ERR_UNKNOWN_ERROR 0xA010FFFF Unknown error(hardware error)

Common questions

Powered by AI

The ROCKEY2 dongle is characterized by its simplicity, low cost, and large memory capacity of 2560 bytes. Unlike ROCKEY4 or ROCKEY5, it does not include many advanced software protection features. ROCKEY2 uses HID technology, eliminating the need for additional drivers on Linux or Windows, and each dongle has a globally unique hardware ID. It supports USB only .

Generating a User ID (UID) for a ROCKEY2 dongle involves using the RY2_GenUID function. This requires a dongle handle obtained from RY2_Open, a 64-byte seed code, and a parameter to set write protection. The UID is derived from the seed code within the dongle hardware, making the process irreversible and ensuring only the user with the seed code can generate the specific UID. The seed code is crucial because it secures the UID generation process against unauthorized duplication .

Setting the initial preformatted status of a ROCKEY2 dongle to UID=0 with a shielded HID ensures that before deployment, the device presents a default state unable to disclose its unique HID. This security measure protects the HID's uniqueness until the deploying developer resets the UID, allowing the a unique identification to be established only post-deployment .

Initially, the ROCKEY2 dongle is preformatted with a User ID (UID) of ‘0’ and a shielded Hardware ID (HID) of ‘0’. The HID is not obtainable and remains shielded while the UID is set to its default value. It is only after the developer resets the UID that the correct HID can be obtained, ensuring the unique HID is not exposed during initial setup .

The block index parameter in the RY2_Read and RY2_Write functions dictates which section of the dongle memory is accessed for reading or writing. The parameter value ranges from 0 to 4, corresponding to memory blocks. This functionality ensures specific memory areas can be targeted directly, providing structured data management and efficient use of the dongle's memory .

The writable or non-writable status of a ROCKEY2 dongle's store zone is determined during the generation of the User ID (UID). This process involves using a 64-byte seed code to generate the UID, and the software vendor can decide if the store zone is writable by setting options during this generation. If the dongle is set to non-writable, the entire memory zone becomes write-protected .

When the UID of a ROCKEY2 dongle is changed, removal and reinsertion of the dongle help the operating system recognize the new UID/HID combination and prompt the relevant driver installation. In systems where multiple dongles are used, setting unique UIDs becomes crucial as it allows multiple dongles to be distinguished and operate concurrently on the same computer without conflicts .

Resetting the UID of a ROCKEY2 dongle influences device recognition since the operating system combines both UID and HID to identify the dongle. Upon resetting the UID, the dongle is perceived as a new device by the computer, necessitating a re-installation of its driver. However, subsequent insertions of the dongle with the same UID/HID combination do not require reinstallation of the driver, provided it has been previously installed .

The error code RY2ERR_NO_SUCH_DEVICE indicates a failure to find the specified dongle, often due to incorrect parameters or a connection issue. Prevention involves ensuring the UID/HID parameters are correct, the dongle is properly connected to the USB port, and the system's USB functionalities are operational. Regular checks and ensuring the correct installation of driver software can also mitigate this issue .

The RY2ERR_WRITE_PROTECT error occurs when there is an attempt to write to a dongle that has been set to be write-protected. This can often happen when the UID generation process involves setting the store zone to non-writable. To resolve this issue, the dongle would need to be reset or reconfigured during the UID generation process to allow writing, assuming such configuration is permissible .

You might also like