Using Dinkey Pro/FD with MATLAB

The Shell protection method supports Windows executables produced by the MATLAB Compiler.

API protection checks in MATLAB are implemented using the M-file ddprotcheck.p to communicate with the dongle via the appropriate shared library (dpwin32.dll on 32-bit Windows, dplin64.so on 64-bit Linux, etc.). You should lock these shared libraries with the API method using DinkeyAdd as described in the user manual, and distribute the locked libraries with your software.

If you are not already familiar with calling shared libraries from MATLAB code, it is strongly recommended that you read the MATLAB documentation on this topic. Depending on your version of MATLAB, you may need to install a C compiler and configure MATLAB to use it with the command mex -setup. Again, refer to the MATLAB documentation for more information.

See Modifying Your Code in the user manual for information on using the API. Below is an overview of how the ddprotcheck function is used in MATLAB.

ddprotcheck Call the Dinkey Pro/FD API.
    [RETCODE,DRIS] = ddprotcheck(LIBNAME,DRIS) calls the API via the
    external library LIBNAME. DRIS is a struct used to pass inputs to the
    API and receive outputs. RETCODE is the return code of the API call.

    [RETCODE,DRIS] = ddprotcheck(LIBNAME,DRIS,@CRYPTFUNCTION) additionally
    provides an extra layer of security. The function CRYPTFUNCTION
    is used to encrypt the DRIS before it is passed between MATLAB and the
    external library.

In MATLAB, the DRIS is a MATLAB structure with some slight differences to the DRIS documented in Structures > DRIS Structure in the user manual. These differences are:

The fields header and size are set automatically by ddprotcheck.p. You do not need to set these fields in your code.
The seed1 and seed2 fields must be 1-by-4 vectors of type uint8, not integers.
rw_data_ptr is replaced by rw_data. This field is the actual data read from/to be written to the dongle (rather than a pointer to it). It should be a 1-by-N vector of type uint8.
When using the functions WRITE_DATA_AREA, ENCRYPT_USER_DATA and DECRYPT_USER_DATA, rw_length is automatically set to be the length of the vector rw_data.
The fields var_a to var_h are replaced by alg_vars. alg_vars must be a 1-by-N vector. The first 8 elements will be used for var_a to var_h. If alg_vars has fewer than 8 elements, it will be padded with zeros.

DRIS fields are automatically converted to the data types specified in Structures > DRIS Structure. When casting, MATLAB truncates values that cannot fit into a variable of the new data type. This can lead to loss of data.

Indices for the secure data area of Plus and Net dongles start at zero. To read the first ten bytes for example, set rw_length = 10 and rw_offset = 0.

In the user manual, possible values for the function and flags fields are referred to by the symbolic names used in other programming languages. Their literal values are provided here for your reference:

Function	Value
PROTECTION_CHECK	1
EXECUTE_ALGORITHM	2
WRITE_DATA_AREA	3
READ_DATA_AREA	4
ENCRYPT_USER_DATA	5
DECRYPT_USER_DATA	6
FAST_PRESENCE_CHECK	7
STOP_NET_USER	8

Flag	Value
DEC_ONE_EXEC	1
DEC_MANY_EXECS	2
START_NET_USER	4
USE_FUNCTION_ARGUMENT	16
CHECK_LOCAL_FIRST	32
CHECK_NETWORK_FIRST	64
USE_ALT_LICENCE_NAME	128
DONT_SET_MAXDAYS_EXPIRY	256
MATCH_DONGLE_NUMBER	512
DONT_RETURN_FD_DRIVE	1024

Before you distribute your application, you must protect it from modification. In general, it is best to use the MATLAB Compiler to create a standalone application that can be run outside of MATLAB. It is also possible to convert your source files to P-code, which protects the code from modification, but still allows it to be run inside the MATLAB environment. However, MathWorks do not recommend P-coding files to protect your intellectual property, as P-code files are obfuscated, not encrypted. See the MATLAB documentation for more information.

MATLAB Example Files

ddprotcheck.p - a P-file that provides a MATLAB interface to the Dinkey Pro/FD API.
dpsample.m - various examples of using ddprotcheck.p.
dinkeyprowin32proto.p - a prototype P-file that defines the signatures of the API functions for 32-bit MATLAB on Windows.
dinkeypro32proto.p - a prototype P-file that defines the signatures of the API functions for 32-bit MATLAB on all other supported platforms.
dinkeypro64proto.p - a prototype P-file that defines the signatures of the API functions for 64-bit MATLAB on all supported platforms.
dp64_thunk.dll - a compatibility layer required by 64-bit MATLAB to use dpwin64.dll.
dp64_thunk.dylib - a compatibility layer required by 64-bit MATLAB to use dpmac64.dylib.
dp64_thunk.so - a compatibility layer required by 64-bit MATLAB to use dplin64.so.

ddprotcheck.p and the appropriate prototype P-file(s) should be used in your own project. If you are using 64-bit MATLAB, you should also include the appropriate thunk file(s) for the platform(s) that you support.

Supported Versions

The MATLAB sample code provided with the Dinkey Pro/FD SDK was written using MATLAB 7 (R14) for Windows, and tested using MATLAB 7 on 32-bit Windows and MATLAB R2013a on 64-bit Windows. All newer versions should be backwards compatible. The sample code may also work with older versions, but no guarantees can be made, and support for older versions is likely to be very limited.

dp64_thunk.dylib and dp64_thunk.so may not be compatible with all versions of MATLAB on all versions of macOS and/or all Linux distributions. If you have problems calling our API on 64-bit macOS or 64-bit Linux, please contact us with full details of the platform and MATLAB version that you are using.

Try It Yourself

The sample code is designed to teach you how to use the Dinkey Pro/FD API in MATLAB programs. Do not copy the examples verbatim into your own code. Experiment with the sample code to understand how the API works, and read the chapter Increasing Your Protection in the user manual for many suggestions on how to make the best use of the API features.

dpsample.m gives simple examples of performing a protection check, as well as using various other features of Dinkey Pro/FD. To run dpsample.m you will first need to use DinkeyAdd to produce a locked copy of the shared library for your platform, and program a dongle (if you are using Plus or Net dongles). Place the locked library in the same folder as the example files and change MATLAB's current directory to this folder. Browse the examples in dpsample.m to see how different features can be used. All the examples follow the same basic pattern:

Set up the DRIS structure with the relevant information.
Call the API.
Use the information returned in the DRIS.

Uncomment the function calls at the top of dpsample.m to enable the examples of different features, then enter dpsample in the Command Window to run the examples.

dpsample.m also demonstrates loading and unloading the appropriate shared library for your platform.

Parts of the sample code marked with !!!! must be customised with your own functions or values for some features to work correctly. Not all features are supported by all dongle models. See the user manual for more information.