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