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

1. Set up the `DRIS` structure with the relevant information.
2. Call the API.
3. 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.