Update Notes for the Dinkey Pro SDK

These notes are intended for customers who are updating their copy of the Dinkey Pro 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 version history.

To be notified by email about new features and other changes to Dinkey Pro hardware and software, log in to your account, go to Account Details and enable Receive Dinkey Pro product updates for your email address.

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

To find the version of your current copy of the Dinkey Pro 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

  • Use the version of DinkeyServer included with the latest SDK. Ensure that this version of DinkeyServer is the one that you distribute to customers with your software.
  • You do not need to change any information stored on the dongle.

Client (Your Protected Software)

  • If you use the API protection method, ensure that your program is using the latest version of the API library.
  • Create a new protected copy of your application using the latest version of DinkeyAdd.

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

  • Changes to the DinkeyAdd user interface.
  • No changes to your code are required.
  • No changes to your saved DinkeyAdd and DinkeyRemote settings (DAPF and DRPF files) are required, unless you want to take advantage of new functionality.

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

  • Changes to the DinkeyAdd and DinkeyRemote user interfaces.
  • Changes to the sample code.
  • Changes to the DAPF file format.
  • No changes to your code are required.
  • No changes to your saved DinkeyAdd and DinkeyRemote settings (DAPF and DRPF files) are required, unless you want to take advantage of new functionality.

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

  • Changes to the sample code.
  • Changes to the DAPF and DRPF file formats.
  • No changes to your code are required, unless you want to take advantage of new functionality.
  • No changes to your saved DinkeyAdd and DinkeyRemote settings (DAPF and DRPF files) are required, unless you want to take advantage of new functionality.

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

  • Changes to the DinkeyAdd user interface.
  • No changes to your code are required.
  • No changes to your saved DinkeyAdd settings (DAPF files) are required, unless you want to take advantage of new functionality.

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

  • Changes to the structure of DinkeyAdd and DinkeyRemote.
  • DinkeyAdd and DinkeyRemote are now available for Mac OS X and Linux, so installing the Windows part of the SDK is no longer required.
  • Changes to the sample code.
  • Changes to your code are required if you call DinkeyAdd or DinkeyRemote programatically.
  • DinkeyWeb deprecated and removed from the SDK.

Details

DinkeyAdd and DinkeyRemote

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

  • DinkeyAdd library - the back end that implements the functionality of DinkeyAdd.
  • DinkeyAdd GUI application - a GUI front end for the library.
  • DinkeyAdd command-line program (DinkeyAddCmd) - a command-line front end for the library.

Similarly, DinkeyRemote is now made up of:

  • DinkeyRemote library - the back end that implements the functionality of DinkeyRemote.
  • DinkeyRemote GUI application - a GUI front end for the library.
  • DinkeyRemote command-line program (DinkeyRemoteCmd) - a command-line front end for the library.

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:

  • You need to call DinkeyAddCmd.exe and DinkeyRemoteCmd.exe instead of DinkeyAdd.exe and DinkeyRemote.exe.

  • The syntax for invoking DinkeyAdd's Data File Encryption tool with specific input and output data files has changed from: 

    C:\> DinkeyAdd.exe /E <input name> <output name>

    to: 

    C:\> DinkeyAddCmd.exe /E /EI<input name> /EO<output name>

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.

Updating from a version earlier than 7.3.0

Summary

  • Improvements to the Shell protection method.
  • Bug fix that may affect users of the Lock Dongle to Computer feature.
  • DAPF and DRPF files can now be saved in JSON format.
  • No changes to your code are required, unless you want to take advantage of new functionality.
  • No changes to your saved DinkeyAdd and DinkeyRemote settings (DAPF and DRPF files) are required, unless you want to take advantage of new functionality.

Details

Shell Method Improvements

The security of the Shell method has been enhanced with additional techniques to prevent debugging of protected code. Improvements have also been made to the way native code is decrypted and executed at runtime, further increasing the strength of Shell protection. If you use the Shell method, we recommend updating your SDK to 7.3.0 and producing a new version of your software locked with the updated Shell method. You may notice that your protected software takes a little longer to load. Once the program has loaded the runtime overhead should be very minimal.

We strongly recommend that you test your updated application thoroughly before releasing it to end users. The new changes to the Shell method have been thoroughly tested with a wide range of EXE and DLL files, but due to the nature of the Shell method and these enhancements, there may be incompatibilities with some files. To report an issue, contact our support team.

Bug Fix Relating to Machine IDs

This information only applies to customers who use the Lock Dongle to User's Computer feature.

There was a bug in previous versions of our runtime code relating to obtaining hardware information about Windows computers (the machine ID). This bug meant that certain updates to Windows 10 could cause the machine ID to change, which would cause protected software to think it was using a dongle locked to a different machine and cause protection checks to return error 944. To resolve this issue, 7.3.0 introduces a change to the algorithm that calculates the machine ID. This change introduces a very small risk of a change to the calculated machine ID on any Windows computer. Customers releasing an update to their protected software that is protected using 7.3.0 should be aware of this risk. If users experience issues with your updated software's protection checks returning error 944, you should use DinkeyRemote to create a secure update code to reset the machine ID stored in their dongle.

JSON DAPF and DRPF Files

DinkeyAdd and DinkeyRemote now support saving and loading their settings in JSON format. This allows you to edit DAPF and DRPF files in a text editor, which is useful to customers who use these tools on macOS and Linux, where they are only currently available as command-line programs. New Quick Tour guides in the Linux and macOS SDKs walk you through adding protection using a sample DAPF file in JSON format.

Support for JSON is also useful for customers who use programming languages that cannot easily manipulate the binary DAPF and DRPF formats. JSON is widely supported by third-party libraries for a huge range of programming languages, allowing you to more easily integrate the functionality of DinkeyAdd and DinkeyRemote into software such as build tools and in-house order management systems.

The DinkeyAdd API has been updated to support the use of JSON DAPF files. ReadDAPFEx() replaces ReadDAPF(), adding a dapf_format parameter that allows you to access the format of the input file. WriteDAPF() has been replaced by WriteDAPFEx(), which allows you to specify the format when writing DAPF settings to disk. ReadDAPF() and WriteDAPF() are still available in the version 7.3 API libraries, so there is no need to modify existing code. Customers should be aware however that they are no longer documented in the user manual and sample code.

Similarly, ReadDRPFEx() and WriteDPRFEx() replace ReadDRPF() and WriteDRPF() in the DinkeyRemote API. These functions are no longer documented, but remain available for use by existing code. See the user manual sections Adding Protection (DinkeyAdd) > DinkeyAdd Module and Remote Parameter Changing > DinkeyRemote for full details of these APIs.

The DinkeyAddCmd and DinkeyRemoteCmd command-line tools have a new /C option that can be used to convert files between binary and JSON formats. See the user manual for full details of how to use this option.

The existing binary formats DAPF and DRPF files are still supported and there are no plans to deprecate them. New features added in future releases will be supported by both binary and JSON formats.

Updating from a version earlier than 7.4.0

Summary

  • Changes to the sample code.
  • Changes to your code are recommended, but not required.

Details

API Changes

New to version 7.4 is the Demo Software Key feature. A demo software key is a time-limited 'virtual dongle' that can be used in place of a physical Dinkey Pro or Dinkey FD device. Demo software keys allow you to offer evaluation copies of your protected software without the need to ship a dongle to every potential new customer, while still protecting your software against copying and enforcing the terms of your licence.

There are two new API functions relating to demo software keys: CreateDemoSoftwareKeyTemplate() in the DinkeyAdd API and DCDownloadDemoSoftwareKey() in the DinkeyChange API. To provide a clear distinction between temporary software keys and demo software keys, some existing API functions and structures have been renamed. The DinkeyAdd API function CreateSoftwareKey() is now CreateTempSoftwareKey(). The SWKEY_INFO structure passed to this function (previously also referred to as SwkeyInfo in some places) is now called TEMP_SWKEY_INFO in the user manual and all code samples. DCDownloadSoftwareKey() in the DinkeyChange API has been renamed to DCDownloadTempSoftwareKey().

The old function names are still supported, so there is no need to change your code to use version 7.4 API libraries, but we recommend using the new names for greater clarity. The original names are no longer documented in the user manual and sample code.

Shell Protection Settings

The DinkeyAdd 7.4 GUI allows you to control the Extra Anti Piracy and Extra Anti Debug settings for Shell-protected Windows EXEs and DLLs. These features were introduced in version 7.3 of the SDK and could not be disabled without manually editing a DAPF file. However, in certain rare cases these features can reduce the loading or runtime speed of the protected application. In version 7.3 these options were supported but undocumented, so there are no changes to the DAPF file format from DinkeyAdd version 7.3. The relevant DAPF file fields are now documented in the user manual.

Updating from a version earlier than 7.5.0

Summary

  • Support for 32-bit applications and OS X versions older than 10.10 Yosemite removed from the macOS SDK.
  • Changes to the DAPF file format. No changes to your saved DinkeyAdd settings files are required, unless you want to take advantage of new functionality.

Details

macOS SDK

Starting with version 7.5, all utilities and dynamic libraries shipped in the macOS SDK are 64-bit only, and support OS X 10.10 Yosemite onwards. API libraries for use in your own applications have all been updated to meet the requirements for notarising your app, including Hardened Runtime requirements.

If you need files compatible with SDK version 7.5 or newer that support 32-bit and/or older versions of OS X, you can contact our support team to request these files. Files available on request are:

  • 32-bit DinkeyAdd, DinkeyRemote and DinkeyChange (command line versions only) for 10.4 Tiger onwards.
  • 32-bit runtime protection API libraries (.o, .dylib and .jnilib) for 10.4 Tiger onwards.
  • 32-bit DinkeyChange API libraries (.dylib and .jnilib) for 10.4 Tiger onwards.
  • 64-bit runtime protection API libraries (.dylib only) for 10.6 Snow Leopard to 10.9 Mavericks.
  • 64-bit DinkeyChange API libraries (.dylib) for 10.6 Snow Leopard to 10.9 Mavericks.

Shell Protection Settings

DinkeyAdd 7.5 introduces even more control over the Extra Anti Piracy setting for Shell-protected native code on Windows. This feature can impact the performance of certain applications, so you can now choose a level of protection between 0 (disabled) and 10 (maximum protection), allowing you to strike a balance between security and performance that is right for your protected software. For binary DAPF files, FileInfo structures have a new field to store this value, ExtraAntiPiracy. In JSON DAPF files, ExtraAntiPiracy is now an integer instead of a boolean. See Structures in the user manual for full details.

DinkeyAdd 7.5 supports older DAPF files that use a binary enabled/disabled value for this feature, so there is no need to modify existing DAPF files unless you want to take advantage of this change.

Updating from a version earlier than 7.6.1

Version 7.6.1 includes improvements to the algorithm that calculates machine IDs from hardware information, increasing the security of features that rely on machine IDs, such as software keys. This improvement may cause a change to the calculated machine ID on some Windows and Linux computers. Macs are not affected by this change.

After updating your protected software to be protected with version 7.6.1:

  • Customers who use temporary software keys and demo software keys: for each software key user, wait until their software key expires before providing the user with the updated software. This removes the possibility of the runtime code calculating a different machine ID to the one that the software key is linked to.

  • Customers who use the Lock Dongle to Computer feature: if a user experience issues with your updated software's protection checks returning error 944, you should use DinkeyRemote to create a secure update code to reset the machine ID stored in their dongle.

Updating from a version earlier than 8.0.0

Version 8.0.0 includes to the algorithm that calculates machine IDs. The update notes for version 7.6.1 also apply when updating your protected software to be protected with version 8, except that changes in version 8 only apply to Linux computers. Devices running Windows and macOS are not affected.