Update Notes for the Dinkey Pro/FD SDK

These notes are intended for customers who are updating their copy of the Dinkey Pro/FD SDK. This document contains details of important changes that may require you to alter the way you add protection and/or distribute your protected software. Not all changes and new features are described here. For a summary of all changes to the SDK, see the Dinkey Pro/FD version history.

Customers who have not used Dinkey Pro or Dinkey FD before, but who are familiar with the original Dinkey system, should read the notes for migrating from Dinkey to Dinkey Pro/FD.

To find the version of your current copy of the Dinkey Pro/FD SDK, open any of the Windows SDK utilities and select Help > About from the menu.

Contents

Updating from a version earlier than 5.6.1

This information applies only to customers who use Dinkey Pro Net or Dinkey FD Net dongles.

Network server auto-detection code was updated in 5.6.1 and is not compatible with previous versions. When updating your software's protection to use the latest SDK, you must make changes to both the server and client.

Server

Client (your protected software)

Updating from a version earlier than 6.0.0

This information applies only to customers who use Pro Plus, Pro Net, FD Plus or FD Net dongles.

Summary

Details

Plus and Net dongles store a list of protection parameter records - each record has a features parameter, an expiry date, an execution counter etc. When adding protection, DinkeyAdd writes these records to the dongle's memory and modifies your EXE file (Shell method) or the API library (API method) to link it to one of these records. In versions before 6.0, the relationship between protected files and the records in the dongle was always 1-to-1, so each record was uniquely identified by the name of the file that was linked to it.

Version 6.0 introduced a way to allow multiple files to be linked to the same record in the dongle by using wildcards when adding protection with DinkeyAdd. This is particularly useful to customers who use DinkeyWeb, and customers who protect cross-platform software (e.g. Java programs), as it is now much easier to protect several files with the same expiry date, execution limit etc.

Records in the dongle are now uniquely identified by the Name in Dongle parameter. When you add protection to your program files, you specify the Name in Dongle of the record that you want to link those files to. The other settings on that dialog are ignored if you choose the Lock Software Only option when adding protection with DinkeyAdd. When creating secure update codes, you should use the Name in Dongle value of the dongle record that you want to update as the Filename parameter in DinkeyRemote. You can still use the *.* wildcard to create codes that update all records in the dongle.

It is also possible to add virtual file records to the dongle, i.e. records that have no file linked to them. This is useful in cases where a single program file contains multiple features that you want to licence separately. You can access virtual file records using the alt_prog_name parameter of the DRIS (API method only). See the user manual chapter Adding Protection (DinkeyAdd) for full details of how to use wildcards and virtual files in DinkeyAdd.

Updating from a version earlier than 6.1.0

This information applies only to customers who use Pro Plus, Pro Net, FD Plus or FD Net dongles.

Summary

Details

Version 6.0 introduced greater separation between the protection parameters stored in a dongle and the protected executable files that are linked to them (see above). Version 6.1 completes this separation, making it clearer and giving you more flexibility when adding protection.

Protection parameters records stored in the dongle are now known as licences. Licences and protected program files are managed on separate tabs in DinkeyAdd. The field that uniquely identifies each record in the dongle is now called Licence Name. When selecting files to protect in DinkeyAdd, you must choose a default licence to link the file to from the drop-down list of defined licences. You can still use wildcards to protect multiple files in the same folder and link them to a single licence. You can now also link files from different folders to the same licence, by adding them as separate items in the list on DinkeyAdd's Programs tab and choosing the same value from the Licence drop-down list for each file. See the user manual chapter Adding Protection (DinkeyAdd) for full details on using DinkeyAdd to define licences, program dongles and lock program files.

To perform protection checks using licences in the dongle other than their default, programs use the DRIS parameter alt_prog_name in versions before 6.1 (API method only). In 6.1, this parameter is now called alt_licence_name, to better describe its purpose. Customers who use this parameter do not need to modify existing code, but should be aware of this change if referring to the sample code again in future, or if starting new projects that will use Dinkey Pro/FD protection.

In DinkeyRemote, the Programs tab is now the Licences tab, to make it clearer that it is the licences in the dongle that are modified by secure update codes.

The DAPF file format (DinkeyAdd saved settings file) has been updated to accommodate the changes in DinkeyAdd. DinkeyAdd 6.1 can open DAPF files created in older versions, and will update older DAPF files to the new version only if you modify any settings and save the changes. Customers who create or modify DAPF files with their own programs do not need to change their code, but should be aware of the new file format when referring to the sample code in version 6.1, or when starting new projects.

Updating from a version earlier than 7.0.0

Summary

Details

New in version 7.0 is the Temporary Software Key feature - a 'virtual dongle' that allows a user to continue to use your protected software while you issue them a replacement for a lost, stolen or damaged dongle.

If you use the API protection method, you can access several new elements of the DRIS structure that relate to software keys. swkey_type will indicates whether your protected software is currently using a software key. If protected software is using a software key, then swkey_exp_day and swkey_exp_month and swkey_exp_year show the software key's expiry date. The DRIS structure in the sample code has been modified to include these extra elements. You do not need to change your existing code unless you would like to access these elements. If you use Net dongles, you will need to update DinkeyServer to version 7.0 to access these new elements in your protected software.

Temporary Software Keys are downloaded and installed on to a user's computer using DinkeyChange. The DinkeyChange API libraries include new functions to enable this, and the sample code has been changed to demonstrate the use of these functions. You do not need to change your code unless you want to take advantage of the new functionality.

Another new feature introduced in version 7.0 is the ability to lock a dongle to a specific computer. This option can be enable when programming the dongle with DinkeyAdd (see Advanced Options on the General tab), and changed (either to reset the lock to a different computer or to remove/add the lock) using DinkeyRemote and DinkeyChange.

The DAPF file format (DinkeyAdd saved settings file) has been updated to support the new features in DinkeyAdd. The DRPF file format (DinkeyRemote saved settings file) has also been updated to support the 'lock dongle to computer' feature. DinkeyAdd 7.0 can open DAPF files created in older versions, and will update older DAPF files to the new version only if you modify any settings and save the changes. Customers who create or modify DAPF files with their own programs do not need to change their code, but should be aware of the new file format when referring to the sample code in version 7.0, or when starting new projects. The same applies to DinkeyRemote and DRPF files.

The following paragraph applies only to customers who Shell-protect .NET assemblies that are compiled to target the 'Any CPU' platform.

When Shell-protecting an 'Any CPU' .NET assembly, previous versions of DinkeyAdd would force the assembly to be 32-bit only and produce only a <filename>.dp32.dll DLL to be shipped with the protected assembly. In version 7.0, the 'Any CPU' target is preserved, and DinkeyAdd creates both a <filename>.dp32.dll and a <filename>.dp64.dll. You must ship both these files with your protected assembly. As with previous versions, these DLLs must be located in the same folder as the protected assembly.

Updating from a version earlier than 7.1.0

Summary

Details

Version 7.1 adds a number of new features to DinkeyAdd, including support for encrypting data files used by your Shell-protected software, advanced options controlling how your protected software behaves at runtime, and a new customisable message for Shell-protected files locked to Net dongles.

Accordingly, the DAPF file format (DinkeyAdd saved settings file) has been updated to accommodate the changes in DinkeyAdd. DinkeyAdd 7.1 can open DAPF files created in older versions, and will update older DAPF files to the new version only if you modify any settings and save the changes. Customers who create or modify DAPF files with their own programs do not need to change their code, but should be aware of the new file format when referring to the sample code in version 7.1, or when starting new projects.

Also new in DinkeyAdd 7.1 is the ability to save settings to DAPF files compatible with older DinkeyAdd versions. This is useful if you use template DAPF files that are modified by your own program and want to make and save changes to those templates using the DinkeyAdd GUI, but don't want to update your program to use the latest DAPF file format.

Updating from a version earlier than 7.2.0

Summary

Details

DinkeyAdd and DinkeyRemote

In version 7.2, DinkeyAdd and DinkeyRemote have each been split into three parts. DinkeyAdd is now made up of:

Similarly, DinkeyRemote is now made up of:

The DinkeyAdd and DinkeyRemote libraries are available for Windows, Mac OS X and Linux, in 32-bit and 64-bit forms. Their APIs are documented in the user manual sections Adding Protection (DinkeyAdd) > DinkeyAdd Module and Remote Parameter Changing > DinkeyRemote respectively. The sample code for C, C# and VB.NET now includes examples of using the APIs in those languages. Using these APIs provides a powerful and flexible way to integrate the functionality of these tools into other software, such as programming dongles or generating secure update codes directly from an order management system used by your sales team.

The GUI applications provide a user interface exactly the same as previous versions of DinkeyAdd and DinkeyRemote. They are currently only available for Windows. These GUI applications now only accept one command-line parameter: the name of a DAPF or DRPF file to open automatically.

The command-line programs provide a much improved alternative to the old method of calling DinkeyAdd and DinkeyRemote with command-line options. They are available for Windows as 32-bit programs, and for OS X and Linux as both 32-bit and 64-bit programs. Previously, output returned from these tools when run with command-line options was limited to the process exit code, and information and errors were displayed only in pop-up GUI windows. DinkeyAddCmd and DinkeyRemoteCmd output information and errors to stdout, which is much more useful, for example, when calling them from a build script or as a post-build event in your IDE.

This new solution may require you to make changes to the way you currently call these programs from another program:

The /B option is redundant as an action is always performed by the command-line tools. If /B is specified, it is ignored.

There are also some new options. For DinkeyAddCmd, /A overrides the action that the DAPF file says DinkeyAdd should perform, and /F locks a specific file, rather than every file listed in the DAPF file. This greatly simplifies certain use cases where it was necessary to have separate DAPF files to lock software and to program dongles, and allows you to modify and protect single files in a large project with many protected files. For DinkeyRemoteCmd, /O allows the secure update code to be output to a file different to the one specified in the DRPF file. See the user manual for a complete list of the command-line options available.

Now that DinkeyAdd and DinkeyRemote are available for OS X and Linux, you do not need to install the Windows SDK on a Windows PC to use Dinkey Pro/FD. However, you may wish to continue using the Windows GUI versions of these tools to edit DAPF and DRPF files or to create new ones, as the GUI is much easier to use.

Sample code for calling the DinkeyAdd and DinkeyRemote libraries on OS X and Linux is included in the SDKs for those platforms. The Mac and Linux SDKs also now include the user manual, as well as runtime protection libraries for cross-platform languages such as Java. For those languages, this allows you to use a single platform to develop your code, compile it and protect it for use on multiple platforms.

API Changes

STOP_NET_USER was previously a flag that could be passed to DDProtCheck() in the DRIS's flags field, but is now also a valid value for the function field. This better reflects its meaning and the action performed by the API library when STOP_NET_USER is used. This value is still accepted as a flag by the API, and DDProtCheck()'s behaviour is unchanged if this flag is passed to it, so there is no need to modify existing code. However, the flag is no longer documented in the user manual and sample code.

DONT_RETURN_FD_DRIVE is a new flag for DDProtCheck() that means that the fd_drive field of the DRIS is not set when a Dinkey FD dongle is detected. In some virtualised environments, the host does not present all of its USB devices to the guest OS correctly: a Dinkey FD dongle may be presented as a copy protection dongle and flash drive connected to two separate virtual USB ports, instead of as a single physical device. This causes DDProtCheck() to fail to detect the flash drive and return an error. If you use Dinkey FD dongles and do not need to access the drive letter or mount name via DDProtCheck(), then we recommend you set this flag to improve performance and reliability.

DinkeyWeb

DinkeyWeb has been superseded by SmartSign, and so starting with version 7.2, DinkeyWeb-related files are no longer included in the SDK. The DinkeyWeb authentication servers will remain live, and we will continue to provide technical support for DinkeyWeb. You do not need to take any action to continue using DinkeyWeb. See this knowledge base article for the latest information about support for DinkeyWeb in major web browsers, including browsers that do not support Java.

In certain situations, you may need version 7.2 or newer of the DinkeyWeb files. These files are available on request. To request the latest version of DinkeyWeb, contact our support team.