Home » Support » User Manual » Licensing system » Integrating to application » Licensing API functions

Licensing API functions

The licensing system API is an integral part of VMProtect API and its SDK. API allows you to specify a serial number and retrieve all information about it: whether it suits the program or not, is the serial number expired, the name this product is registered to and so on. Also, the API provides a hardware identifier of the computer the program runs on.

VMProtectSetSerialNumber

This function loads a serial number to the licensing system. Call syntax:

int VMProtectSetSerialNumber(const char *SerialNumber);

The input SerialNumber parameter must contain a pointer to a null-terminated string (‘\0′) containing a base-64 encoded serial number. The function returns a bit mask of serial number status flags, the same as the one VMProtectGetSerialNumberState() returns. You can read more about flags below. The serial number is “good” if the function returned 0.

VMProtectGetSerialNumberState

This function returns status flags for the serial number specified by a call to VMProtectSetSerialNumber().

int VMProtectGetSerialNumberState();

If at least one flag is set, there is a problem with the serial number. The program shouldn’t work if at least one bit is set. The detailed description of flags and their values is listed in the table below:

Flag Value Description
SERIAL_STATE_FLAG_CORRUPTED 0×00000001 The licensing system is corrupted. Possible reasons are: incorrect setup of the protection project, cracking attempt.
SERIAL_STATE_FLAG_INVALID 0×00000002 The serial number is incorrect. The flag is set if the licensing system cannot decrypt the serial number.
SERIAL_STATE_FLAG_BLACKLISTED 0×00000004 The serial number matches the product, but is black listed in VMProtect.
SERIAL_STATE_FLAG_DATE_EXPIRED 0×00000008 The serial number is expired. You can obtain the detailed information about the expiration date by calling VMProtectGetSerialNumberData()
SERIAL_STATE_FLAG_RUNNING_TIME_OVER 0×00000010 Operating time of the program is depleted. You can obtain the detailed information about the operating time of the program by calling VMProtectGetSerialNumberData()
SERIAL_STATE_FLAG_BAD_HWID 0×00000020 Hardware identifier does not match the hardware identifier prescribed in the key.
SERIAL_STATE_FLAG_MAX_BUILD_EXPIRED 0×00000040 The serial number does not match the current version of the protected program. You can obtain the maximum build date of the program this serial number matches by calling VMProtectGetSerialNumberData().

VMProtectGetSerialNumberData

This function obtains information about contents of the serial number acquired with a call to VMProtectSetSerialNumber(). Call syntax:

bool VMProtectGetSerialNumberData(VMProtectSerialNumberData *Data, int Size);

The first parameter is a pointer to the VMProtectSerialNumberData structure, where all necessary information will be written to. The second parameter is the size of the structure passed in the first parameter. It is required to control the structure’s format. The function returns FALSE if the licensing system is corrupted (see the SERIAL_STATE_FLAG_CORRUPTED flag), if a zero address of the structure is provided or if the passed size of the structure is incorrect. In all other cases, the function returns TRUE and records all information about the serial number to the provided address. Below are the elements of the structure:

Element Type Description
nState int A bit flag mask indicating the status of a key. Similar to the one returned by VMProtectGetSerialNumberState().
wUserName wchar_t[256] The name of a customer in UNICODE, null-terminated.
wEMail wchar_t[256] The e-Mail of a customer in UNICODE, null-terminated.
dtExpire VMProtectDate The key expiration date. The format of the VMProtectDate structure is described below.
dtMaxBuild VMProtectDate The maximum product build date the given key can work with. The format of the VMProtectDate structure is described below.
bRunningTime int The amount of minutes the program will work (maximum duration of a session). The value in minutes counts from the moment the program starts.
nUserDataLength unsigned char The length of user data in the bUserData field.
bUserData unsigned char[255] User data put into the key. The actual number of bytes is specified in nUserDataLength.

The VMProtectDate structure is a compact representation of date. Its fields are listed in the table below:

Element Type Description
wYear unsigned short Year.
bMonth unsigned char Month, starts from 1.
bDay unsigned char Day, starts from 1.

VMProtectGetCurrentHWID

This function obtains a hardware identifier of the PC the program is working on. Call syntax:

int VMProtectGetCurrentHWID(char * HWID, int Size);

The first parameter is a pointer to a memory area where the identifier is written to. The second parameter is the size of this area. The function returns the number of bytes written inclusive of the trailing zero byte (‘\0′). If NULL is provided in the first parameter, the function returns the number of bytes required to store the hardware identifier. Here is the correct way to use the function:

int nSize = VMProtectGetCurrentHWID(NULL, 0); // get the required buffer size
char *pBuf = new char[nSize]; // allocate memory for the buffer
VMProtectGetCurrentHWID(pBuf, nSize); // obtain the identifier
// use the identifier
delete [] pBuf; // release memory