# Генераторы ключей: Windows-версия

### Описание

Генератор для Windows представляет собой DLL-файлы для платформ x86 и x64, заголовочный файл языка C и lib-файл, совместимый с MSVC. Таким образом, библиотека может быть как слинкована статически, так и загружаться динамически.

Все файлы генератора находятся в каталоге Keygen\DLL, там же находится тестовое приложение, которое генерирует серийные номера.

### API генератора

Генератор экспортирует всего две функции: одна непосредственно генерирует серийный номер, вторая - освобождает память, выделенную первой. Начнем с первой и основной функции:

    VMProtectErrors __stdcall VMProtectGenerateSerialNumber(
                                    VMProtectProductInfo * pProductInfo,
                                    VMProtectSerialNumberInfo * pSerialInfo,
                                    char ** pSerialNumber
                            );

Первый параметр - указатель на структуру VMProtectProductInfo, содержимое которой выгружается в VMProtect (см. Экспорт параметров продукта). Структура содержит приватный ключ продукта, используемый алгоритм и количество бит, а также идентификатор продукта. Подробнее о заполнении этой структуры написано ниже.

Второй параметр - указатель на структуру VMProtectSerialNumberInfo, содержимое которой переносится в генерируемый серийный номер. Структура содержит все поля серийного номера, а также битовую маску, определяющую какие именно поля должны быть записаны в серийный номер.

    struct VMProtectSerialNumberInfo
    {
            INT              flags;
            wchar_t *        pUserName;
            wchar_t *        pEMail;
            DWORD            dwExpDate;
            DWORD            dwMaxBuildDate;
            BYTE             nRunningTimeLimit;
            char *           pHardwareID;
            size_t           nUserDataLength;
            BYTE *           pUserData;
    };

Поле flags содержит битовые флаги из набора VMProtectSerialNumberFlags, описанного перед структурой:

- HAS_USER_NAME - поместить в серийный номер имя пользователя, находящееся в переменной pUserName.
- HAS_EMAIL - поместить в серийный номер e-mail пользователя, находящийся в переменной pEMail.
- HAS_EXP_DATE - серийный номер перестанет действовать поле окончания дня, указанного в переменной dwExpDate.
- HAS_MAX_BUILD_DATE - серийный номер будет подходить только к версиям продукта, созданным до даты, указанной в переменной dwMaxBuildDate.
- HAS_TIME_LIMIT - программа перестанет работать по истечении времени, указанного в переменной nRunningTimeLimit (время указывается в минутах и не может превышать 255).
- HAS_HARDWARE_ID - программа будет работать только на оборудовании с идентификатором, указанным в переменной pHardwareID.
- HAS_USER_DATA - поместить в серийный номер пользовательские данные длинной nUserDataLength, расположенные по адресу, указанному в переменной pUserData.

Третий параметр - указатель на указатель. Туда будет записан адрес сгенерированного серийного номера. После генерации номер необходимо скопировать, а адрес передать во вторую функцию API генератора, которая освободит занимаемую серийным номером память.

    void __stdcall VMProtectFreeSerialNumberMemory(char * pSerialNumber);

Функция VMProtectGenerateSerialNumber возвращает значение типа VMProtectErrors, содержащее 0 в случае успешной генерации номера или код ошибки в противном случае. Возможны следующие коды ошибок:

- ALL_RIGHT - ошибок нет, номер сгенерирован успешно.
- UNSUPPORTED_ALGORITHM - в первом параметре функции передан некорректный алгоритм шифрования ключа.
- UNSUPPORTED_NUMBER_OF_BITS - в первом параметре функции передано некорректное количество бит в ключе.
- USER_NAME_IS_TOO_LONG - длина имени пользователя в кодировке UTF-8 превысила 255 байт.
- EMAIL_IS_TOO_LONG - длина e-mail пользователя в кодировке UTF-8 превысила 255 байт.
- USER_DATA_IS_TOO_LONG - длина пользовательских данных превышает 255 байт.
- HWID_HAS_BAD_SIZE - идентификатор оборудования имеет некорректный размер.
- PRODUCT_CODE_HAS_BAD_SIZE - идентификатор продукта, переданный в первом параметре функции, имеет неверный размер.
- SERIAL_NUMBER_TOO_LONG - серийный номер слишком длинный и не помещается в указанное в алгоритме количество бит.
- BAD_PRODUCT_INFO - первый параметр функции некорректен или NULL.
- BAD_SERIAL_NUMBER_INFO - второй параметр функции некорректен или NULL.
- BAD_SERIAL_NUMBER_CONTAINER - третий параметр функции не указывает на ячейку памяти для записи адреса серийного номера.
- NOT_EMPTY_SERIAL_NUMBER_CONTAINER - третий параметр функции не указывает на пустую ячейку, в ячейке должно быть значение NULL.
- BAD_PRIVATE_EXPONENT - значение приватной экспоненты в первом параметре функции некорректно.
- BAD_MODULUS - значение модуля в первом параметре функции некорректно.

Ошибки делятся на две категории: те, что связаны с некорректными параметрами или с содержимым первого параметра функции, и все остальные. Ошибки первой категории редки и являются признаком некорректной настройки структуры. Имеет смысл выгрузить информацию о продукте повторно и убедиться, что структура заполняется правильно. Пример правильного заполнения приведен ниже.

Ошибки второй категории связаны с попыткой вместить в ключ больше данных, чем это возможно ввиду его размера. В таком случае разумно будет отправить регистратору вместо ключа текст "Ключ будет выслан в течение суток", а всю необходимую информацию отправить себе по почте. Ключ в таком случае генерируется в VMProtect в ручном режиме, какие-то данные обрезаются, чтобы уместить все необходимое в максимальный размер ключа.

### Пример использования

Ниже приведен пример кода, который вызывает две вышеописанные функции и генерирует серийный номер. Обратите внимание на блок кода, расположенный в самом начале. Пример не будет работать пока вы не замените его на блок, выгруженный для продукта из VMProtect:

    //////////////////////////////////////////////////////////////////////////
    // !!! this block should be generated by VMProtect !!!                 ///
    //////////////////////////////////////////////////////////////////////////

    VMProtectAlgorithms g_Algorithm = ALGORITHM_RSA;
    size_t g_nBits = 0;
    byte g_vModulus[1];
    byte g_vPrivate[1];
    byte g_vProductCode[1];

    //////////////////////////////////////////////////////////////////////////
    //////////////////////////////////////////////////////////////////////////

    int _tmain(int argc, _TCHAR* argv[])
    {
            VMProtectProductInfo     pi;
            pi.algorithm = g_Algorithm;
            pi.nBits = g_nBits;
            pi.nModulusSize = sizeof(g_vModulus);
            pi.pModulus = g_vModulus;
            pi.nPrivateSize = sizeof(g_vPrivate);
            pi.pPrivate = g_vPrivate;
            pi.nProductCodeSize = sizeof(g_vProductCode);
            pi.pProductCode = g_vProductCode;

            VMProtectSerialNumberInfo si = {0};
            si.flags = HAS_USER_NAME | HAS_EMAIL;
            si.pUserName = L"John Doe";
            si.pEMail = L"john@doe.com";
            char * pBuf = NULL;
            VMProtectErrors res = VMProtectGenerateSerialNumber(&pi, &si, &pBuf);
            if (res == ALL_RIGHT)
            {
                    printf("Serial number:\n%s\n", pBuf);
                    VMProtectFreeSerialNumberMemory(pBuf);
            }
            else
            {
                    printf("Error: %d\n", res);
            }

            return 0;
    }

Этот пример с проектом для Microsoft Visual Studio находится в каталоге Keygen\DLL\Example, ниже будут описаны наиболее интересные места кода.

Первые строчки функции main заполняют структуру VMProtectProductInfo данными, выгруженными из VMProtect. Этот код стандартен, его не следует менять во избежание появления ошибок. Далее создается структура VMProtectSerialNumberInfo, в поле флагов выставляется комбинация из битов имени пользователя и e-mail. Строчкой ниже в соответствующие поля структуры заносятся значения имени пользователя и пароля. Обратите внимание, что значения принимаются в кодировке UNICODE. Генератор ключей внутри преобразует их в кодировку UTF-8.

Далее описывается переменная-указатель, куда будет записан адрес сгенерированного ключа, и вызывается функция VMProtectGenerateSerialNumber, после чего анализируется код возврата. Если ошибок нет, то сгенерированный номер печатается на консоль и вызывается функция осовобождения памяти.

### Остальные поля структуры VMprotectSerialNumberInfo

Некоторые поля структуры требуют дополнительных поясненений. К примеру, поля dwExpDate и dwMaxBuildDate содержат даты в определенном формате: 0xYYYYMMDD, т.е. год хранится в старшем слове, а месяц и день в старшем и младшем байтах младшего слова. Для формирования такого числа описан макрос MAKEDATE(y, m, d), который можно вызвать так: MAKEDATE(2010, 05, 12).

В поле pHardwareID должен быть записан указатель на строку, которую вернул метод VMProtectGetCurrentHWID из SDK лицензирования.

© 2006-2015 Copyright VMProtect Software