The licensing system API is an integral part of the VMProtect API and its SDK. The API allows you to specify a serial number and retrieve all information about it: whether it is valid for the program, whether it has expired, the name it is registered to, and so on. In addition, the API provides a hardware identifier of the computer on which the program is running.
VMProtectSetSerialNumber
This function loads a serial number into 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 Base64-encoded serial number. The function returns a bitmask of serial number status flags, the same as those returned by VMProtectGetSerialNumberState(). You can read more about the flags below. The serial number is considered valid if the function returns 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 should not run if any bit is set. The detailed description of flags and their values is listed in the table below:
| Flag | Value | Description |
|---|---|---|
| SERIAL_STATE_FLAG_CORRUPTED | 0x01 | The licensing system is corrupted. Possible reasons include incorrect protection project configuration or a cracking attempt. |
| SERIAL_STATE_FLAG_INVALID | 0x02 | The serial number is invalid. This flag is set if the licensing system cannot decrypt the serial number. |
| SERIAL_STATE_FLAG_BLACKLISTED | 0x04 | The serial number matches the product but is blacklisted in VMProtect. |
| SERIAL_STATE_FLAG_DATE_EXPIRED | 0x08 | The serial number has expired. Detailed information about the expiration date can be obtained by calling VMProtectGetSerialNumberData(). |
| SERIAL_STATE_FLAG_RUNNING_TIME_OVER | 0x10 | The program’s operating time has expired. Detailed information can be obtained by calling VMProtectGetSerialNumberData(). |
| SERIAL_STATE_FLAG_BAD_HWID | 0x20 | The hardware identifier does not match the one specified in the serial number. |
| SERIAL_STATE_FLAG_MAX_BUILD_EXPIRED | 0x40 | The serial number is not valid for the current version of the protected program. The maximum build date can be obtained by calling VMProtectGetSerialNumberData(). |
VMProtectGetSerialNumberData
This function retrieves information about the contents of the serial number set via a call to VMProtectSetSerialNumber(). Call syntax:
bool VMProtectGetSerialNumberData(VMProtectSerialNumberData *Data, int Size);The first parameter is a pointer to a VMProtectSerialNumberData structure where all necessary information will be written. The second parameter is the size of the structure, used to validate its format. The function returns FALSE if the licensing system is corrupted (see the SERIAL_STATE_FLAG_CORRUPTED flag), if a NULL pointer is provided, or if the structure size is incorrect. In all other cases, the function returns TRUE and fills the structure with serial number data.
The structure fields are listed below:
| Element | Type | Description |
|---|---|---|
| nState | int | A bitmask representing the serial number state, similar to the value returned by VMProtectGetSerialNumberState(). |
| wUserName | wchar_t[256] | The customer name in Unicode (null-terminated). |
| wEMail | wchar_t[256] | The customer e-mail in Unicode (null-terminated). |
| dtExpire | VMProtectDate | The license expiration date. The format of the VMProtectDate structure is described below. |
| dtMaxBuild | VMProtectDate | The maximum build date the serial number is valid for. The format is described below. |
| bRunningTime | int | The number of minutes the program is allowed to run per session (maximum 255 minutes). |
| nUserDataLength | unsigned char | The length of user data stored in bUserData. |
| bUserData | unsigned char[255] | Custom user data stored in the serial number. The actual size is specified in nUserDataLength. |
VMProtectDate
This structure is a compact representation of a date. Its fields are listed below:
| Element | Type | Description |
|---|---|---|
| wYear | unsigned short | Year. |
| bMonth | unsigned char | Month (starting from 1). |
| bDay | unsigned char | Day (starting from 1). |
VMProtectGetCurrentHWID
This function retrieves the hardware identifier of the computer on which the program is running. Call syntax:
int VMProtectGetCurrentHWID(char * HWID, int Size);The first parameter is a pointer to a memory buffer where the identifier will be written. The second parameter is the size of that buffer. The function returns the number of bytes written, including the trailing null byte (‘\0’). If NULL is passed as the first parameter, the function returns the required buffer size.
Correct usage example:
int nSize = VMProtectGetCurrentHWID(NULL, 0); // get required buffer size
char *pBuf = new char[nSize]; // allocate memory
VMProtectGetCurrentHWID(pBuf, nSize); // retrieve identifier
// use the identifier
delete [] pBuf; // free memory