Migrating from Dinkey to Dinkey Pro/FD

These notes are intended for customers who have protected software with the original Dinkey dongles,
and are now upgrading their protection to use Dinkey Pro or Dinkey FD dongles.

Customers updating their Dinkey Pro/FD SDK from an older version should read the
Dinkey Pro/FD version history
for a list of changes, and the Dinkey Pro/FD update notes
for full details of important changes that may require you to alter the way you add protection and/or distribute your protected software.

Contents

Evaluating Dinkey Pro/FD Before Migrating

These notes and the Dinkey Pro/FD SDK user manual should provide all the information you need
to assess the work involved in upgrading your software's protection.
The Dinkey Pro/FD SDK is free for existing customers; see the SDK notes below for details of how to obtain this SDK.
The easiest way to get Pro or FD dongles to evaluate is to order them through our
secure online order system.
We offer a 30-day no quibble guarantee,
which allows you to return the dongles for a full refund if they do not suit your needs for any reason at all.

The Dongles

All Dinkey dongles have direct equivalents in the Dinkey Pro and Dinkey FD ranges:

Old Model

Equivalent Dinkey Pro Model

Equivalent Dinkey FD Model

Dinkey 1S

Dinkey Pro Lite

Dinkey FD Lite

Dinkey 2

Dinkey Pro Plus

Dinkey FD Plus

DinkeyNet

Dinkey Pro Net

Dinkey FD Net

Dinkey Pro and FD dongles are driverless so there is no need for the user to install drivers on their PC.
Linux users: as with Dinkey dongles, users must run a bash script once (as root) to configure the correct access rights to Pro and FD dongles.

If you protect multiple different products with the Dinkey system,
by default Dinkey 1S dongles will work with any and all of these products.
Limiting which product(s) a Dinkey 1S dongle works with requires the use of multiple SDSNs or custom dongle serial numbers.
Dinkey Pro Lite and Dinkey FD Lite dongles contain a product code (chosen by you when you place an order)
to allow you to control which protected product(s) each dongle can be used with.

Dinkey Pro and FD dongles have many extra features that Dinkey dongles do not have.
Some examples:

All data stored in the dongle is stored in the same secure smart card memory used in credit cards.

Communication with the dongle uses RSA encryption.

The dongle's hardware encryption engine can be used to encrypt/decrypt your own data.

A much larger secure data area.

No limit on the number of different files that can be locked to a dongle.

Support for more complex user algorithms.

The ability to encrypt all parameters passed to our API, securing the link between your code and ours.

See the user manual for information about these features.

Dinkey Pro dongles are available in two different form factors.
'Standard' Pro dongles look exactly the same as Dinkey dongles, and are available in green, bronze and blue.
'Mini' Pro dongles measure just 19 x 17 x 7 mm, making them ideal for use with laptops, tablet PCs and embedded systems.
They can be ordered in black and green or black and blue.
Dinkey FD Lite dongles are black; Dinkey FD Plus and Net dongles are available in white and red.

The SDK

Dinkey Pro/FD uses a different SDK to the original Dinkey system.
This SDK is provided free of charge to our existing customers.
A link to download the latest version of the SDK will be sent to you
when you place your first order for Dinkey Pro or FD dongles.
Your SDSN remains the same.

The programs in the old Dinkey SDK all have direct equivalents in Dinkey Pro/FD:

Task

Old Program

Equivalent in Dinkey Pro/FD

Adding protection

DDAdd

DinkeyAdd

Generating codes to update end users' dongles

DDRemote

DinkeyRemote

Applying remote update codes

DDChange

DinkeyChange

Viewing the settings stored in a dongle

DDLook

DinkeyLook

Communicating between protected software and network dongles

DDNet

DinkeyServer

DinkeyLook is a developer tool and should not be distributed to end users. DinkeyChange can be used to create an encrypted diagnostic file that you can open with DinkeyLook to view the current state of a user's dongle.

Similarly, the file formats used by the SDK programs have direct equivalents:

File Content

Old File Extension

Equivalent in Dinkey Pro/FD

Saved settings for adding protection

.ddp

.dapf

Saved settings for creating remote update codes

.ddr

.drpf

Encrypted representation of settings stored in a dongle

.ddl

.dlpf

The Shell Protection Method

If you use the Shell method to protect your software then no changes to your software are necessary.
Simply create a Shell-protected copy of your application using DinkeyAdd rather than DDAdd.

The Shell method can be used to protect 32-bit and 64-bit EXEs and DLLs. Both native executables and .NET assemblies are supported.
The Shell method can also be used to protect PDF documents.

It is not possible to produce a Shell-protected program that will work with both Dinkey and Dinkey Pro/FD dongles.

New versions of your software should be protected using Dinkey Pro/FD.
If you want to distribute new versions as an update to existing customers, two choices are available to you:

Maintain two separate versions of your software.
Distribute the version protected with Dinkey as an update for existing customers.
Distribute the version protected with Dinkey Pro/FD to new customers (and later as an update for these customers).

The Object Protection Method

The Object protection method is known as the API method in Dinkey Pro/FD.
The Dinkey Pro/FD API is not the same as the API used in the older Dinkey system,
so you will need to make some changes to your software. The basic principles of the API remain the same however,
so those who have used the Dinkey API will find it straightforward to get to know the Dinkey Pro/FD API.
The main differences include:

The structure used by the Dinkey Pro/FD API is called the DRIS (Dinkey Runtime Information Structure).
This structure replaces the DDMB used with the old Dinkey API.

When reading or writing the secure data area of a Dinkey Pro or FD dongle,
the buffer used to pass the data to/from the API no longer requires a header
(previously the first 4 bytes of the buffer had to be the ASCII characters "DDAT").

The update number in Dinkey Pro and FD dongles starts at 1.
The runtime, DinkeyChange and DinkeyLook all display the same update number for a given Plus or Net dongle.
(In the old Dinkey system, the update number starts at 0. DDChange and DDLook display a Next Update Number value,
which is 1 higher than the update number returned in the DDMB at runtime.)

The Dinkey Pro/FD runtime never displays any messages or dialogs.

For more information, see the API reference in the user manual. We recommend that you read the whole of the chapter Modifying Your Code to familiarise yourself with the Dinkey Pro/FD API.

The Dinkey Pro/FD API offers all the same functionality of the Dinkey API,
as well as providing access to the new features of Dinkey Pro/FD dongles mentioned above.
The table below summarises and compares the most common actions performed using the two APIs.

Use any valid ddmb.function value except 1 with
valid values for ddmb.rw_offset, ddmb.rw_length and rw_data_ptr

Use dris.function = READ_DATA_AREA

Release a network user

Use ddmb.function = 6

Use any valid value for dris.function
with dris.flags = STOP_NET_USER

Execute an algorithm

Use any valid ddmb.function value with
any valid value for ddmb.alg_number

Use dris.function = EXECUTE_ALGORITHM

By modifying your code to use both the Dinkey and Dinkey Pro/FD APIs,
you can produce a version of your protected software that can be used with either dongle.
This allows you to distribute the same software to all customers,
regardless of whether it is an update for an existing customer with a Dinkey dongle
or they are a new customer that will use a Dinkey Pro or FD dongle.

Since Dinkey Pro/FD provides all the functionality that Dinkey provides,
you can simply modify your code to try an action with one API,
then try the action with the second API if the first fails.
The following pseudocode gives an example of performing a basic protection check:

To get the best performance when using this technique, call the Dinkey Pro/FD API first, as in the example. Dinkey Pro/FD API calls return more quickly than Dinkey API calls if no dongle is present.

Your software must also include both runtimes, and be locked with both DDAdd and DinkeyAdd.

Static library (.obj and .o file) users should link both libraries when compiling their executable,
and lock the same executable file with DDAdd and DinkeyAdd.

Dynamic library (.dll, .dylib and .so file) users should reference both libraries from their executable,
and lock the Dinkey runtime with DDAdd and the Dinkey Pro/FD runtime with DinkeyAdd.
Both library files should be shipped alongside the protected executable.