Migrating from Dinkey to Dinkey Pro

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 dongles.

Customers updating their Dinkey Pro SDK from an older version should read the Dinkey Pro version history for a list of changes, and the Dinkey Pro 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.

Evaluating Dinkey Pro Before Migrating
The Dongles
The SDK
The Shell Protection Method
The Object Protection Method

Evaluating Dinkey Pro Before Migrating

These notes and the Dinkey Pro SDK user manual should provide all the information you need to assess the work involved in upgrading your software's protection. The Dinkey Pro 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 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 range:

Old Model	Equivalent Dinkey Pro Model
Dinkey 1S	Dinkey Pro Lite
Dinkey 2	Dinkey Pro Plus
DinkeyNet	Dinkey Pro Net

Dinkey Pro 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 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 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 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.

The SDK

Dinkey Pro 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 dongles. Your SDSN remains the same.

You can request the latest version of the SDK at any time by filling in the form on this page. For security, download links will only be sent to registered email addresses. To manage the registered addresses for your account, log in to our online order system and go to Account Details.

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

Task	Old Program	Equivalent in Dinkey Pro
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
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 dongles.
New versions of your software should be protected using Dinkey Pro. If you want to distribute new versions as an update to existing customers, two choices are available to you:
1. Maintain one version of your software, protected with Dinkey Pro. Replace your existing customers' Dinkey dongles with Dinkey Pro dongles.
2. 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 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. The Dinkey Pro 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 API. The main differences include:

The structure used by the Dinkey Pro 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 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 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 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 API.

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

Action	Dinkey API	Dinkey Pro API
Basic protection check; decrement execution count and start network user where appropriate	Use `ddmb.function = 0`	Use `dris.function = PROTECTION_CHECK` with both `DEC_ONE_EXEC` and `START_NET_USER` set in `dris.flags`
Basic protection check; no change to execution count and network user count	Use `ddmb.function = 2`	Use `dris.function = PROTECTION_CHECK` with `dris.flags = 0`
Write dongle data area	Use `ddmb.function = 1`	Use `dris.function = WRITE_DATA_AREA`
Read dongle data area	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 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 dongle.

Since Dinkey Pro 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:
```
dris.header = "DRIS";
dris.size = sizeof(dris);
dris.function = PROTECTION_CHECK;
dris.flags = DEC_ONE_EXEC | START_NET_USER;

if (DDProtCheck(&dris, null) != 0)  // Dinkey Pro check failed
{
  ddmb.ddmb = "DDMB";
  ddmb.func = 0;
  ddmb.flags = 0;
  ddmb.rw_offset = 0;
  ddmb.rw_length = 0;

  if (DDWIN32(&ddmb) != 0)    // Dinkey check failed
  {
    // No valid dongle found
    // Handle this in the appropriate way for your program
  }
}
```
To get the best performance when using this technique, call the Dinkey Pro API first, as in the example. Dinkey Pro 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 runtime with DinkeyAdd. Both library files should be shipped alongside the protected executable.