Защита дополнений в деталях

Приветствую. Эта заметка будет полезна скорее для уже состоявшихся авторов компонентов, но возможно начинающим тоже будет полезно изучить механизм и позволит стать будущими авторами дополнений, если ещё в раздумьях.

Не так давно некоторые дополнения на modstore.pro обзавелись защитой. Дополнения можно по прежнему устанавливать из репозитория, но если попробовать скопировать архив с пакетом на другой сайт, то установить ничего не получится. И это было сделано не спроста, так как наглости некоторых людей нет предела, пришлось предпринять меры.

Следом авторам платных дополнений разослали инструкцию о том, каким образом встроить подобную защиту в собственные дополнения. Стоит отметить, что с первого раза сделать по инструкции (несмотря на простоту) не получилось в силу особенностей применяемого варианта сборки пакета. Пришлось разбираться досконально и выяснять, как и что в MODX работает, чтобы сделать это “правильно” и надежно.

Прежде чем продолжить, стоит ознакомиться с специальным методом сборки пакетов – «Сборка transport-пакета без установки MODX». Инструкция написана в далеком 2015 году, однако описанный метод работает до сих пор. Отличие в том, что подход не требует установки MODX для сборки пакета, т.е. сборку запустить можно откуда угодно, имея только исходники пакета и xPDO.

Детали внутри.

Немного теории о защите

Для начала разберемся, как работает механизм защиты.

В репозитории пакетов, в нашем случае modstore.pro, когда добавляется платный компонент и туда загружается собранный архив с конкретной версией, для пакета и загруженной версии создается некий пароль. Этот пароль доступен через API. Чтобы получить пароль, в запросе передаётся email, ключ для доступа к пакетам репозитория, название пакета и версия. С помощью этого пароля при последующей сборке пакет зашифруется. После сборки зашифрованный пакет опять загружается в репозиторий, при этом просто заменяется архив, без поднятия версии. Когда пользователь будет устанавливать пакет, в момент установки этот пароль будет заново запрашиваться и содержимое элементов пакета расшифруется. Если же устанавливать такой пакет без подключения к провайдеру или без наличия оплаты для ключа, расшифровка будет невозможна.

Теперь разберемся, что же сделать, чтобы зашифровать пакет, однако перед этим разберемся, как работают пакеты в MODX в момент установки.

Как устроены пакеты MODX

Хоть с виду это кажется высшей математикой, но пакеты в MODX устроены примитивно. Главный исполняемый файл пакета – это `manifest.php`. В этом файле хранится мета-информация (список изменений, лицензия, зависимости) и массив отдельных транспортных объектов (vehicles) с инструкциями по установке и ссылками на файлы с содержимым этих объектов.

В коде MODX описано 3 типа таких объектов и каждый отличается характером поведения в момент установки и владеет дополнительными возможностями.

xPDOObjectVehicle

Стандартный и часто используемый тип. Этот тип описывает объекты MODX, которые будут созданы в системе. С помощью xPDOObjectVehicle в пакет упаковываются категории, снипеты, чанки, ресурсы и другие объекты MODX, которые наследуют класс xPDOObject.

xPDOFileVehicle

Этот тип используется реже. Тип сильно проще xPDOObjectVehicle и указывает, что файл из пакета будет помещен в указанный каталог в MODX в момент установки.

xPDOScriptVehicle

Редко востребован, но иногда полезен. Похож на xPDOFileVehicle, но вместо копирования файла исполняет файл, как PHP скрипт.

Элементы массива `manifest-vehicles` выполняются в той последовательности, в которой перечислены в этом массиве. Это крайне важно для понимания механизма внедрения защиты и мы к этому вернемся чуть позже.

Скрипт сборки

Скрипт сборки, пожалуй, неизведанная область, даже для уже состоявшихся авторов дополнений (особенно тех, кто слепо копирует modExtra и подобные решения). Сразу оговорюсь, что считаю такие инструменты полезными и экономящими время, но только если эти инструменты использовать вдумчиво и предварительно разобравшись в том, что они делают.

Скрипт сборки выполняет простую задачу – собирает необходимые элементы, упаковывает каждый в транспортный объект, записывает содержимое элементов в файлы, описывает в файле-манифесте порядок установки и архивирует в итоговый пакет.

Вот простой сборщик пакета, который при установке копирует файл robots.txt из пакета в корень сайта.

...
// создаем объект пакета
// передаем в конструктор объект xPDO
// название и версию пакета
// и путь, куда будет сохранен архив с собранным пакетом
$package = new xPDOTransport($xpdo, 'robots-1.0.0-pl', __DIR__ . '/../_pkg/');

// добавляем в пакет транспортный объект (vehicle) типа Файл 
// в массиве с параметрами описываем путь, где лежит исходный файл
// и путь, куда файл должен быть перемещен из пакета в момент установки
$package->put(new xPDOFileVehicle, [
    'vehicle_class' => xPDOFileVehicle::class,
    'object' => [
        'source' => __DIR__ . '/robots.txt',
        'target' => "return MODX_BASE_PATH;"
    ]
]);

// упаковываем пакет в архив
$package->pack()

В коде опущены инициализации переменных и подключения классов, но логика умещается в десяток строк. Разобраться не сложно.

Шифровальщик

Теперь вернемся к нашей непосредственной задаче – шифрованию. Для целей шифрования элементов пакета вместе с инструкцией представляется специальный класс – EncryptedVehicle. Сразу скажу, что класс Василия, и авторство я присваивать не собираюсь.

Класс наследует базовый класс транспортного объекта xPDOObjectVehicle и переопределяет методы `put`, `install` и `uninstall`, добавляя функции по шифрованию и расшифровке содержимого элементов. Как ключ для шифровки/дешифровки используется пароль, выдаваемый modstore.pro через специальное API.

Этот класс – это по сути четвертый тип транспортного объекта, который может использоваться для описания элементов в пакете. Таким образом, если хотим зашифровать содержимое, то при добавлении элемента в пакет используем этот класс. Вот пример:

$package->put($object, [
    'vehicle_class' => EncryptedVehicle::class,
    ...
]);

Будьте внимательны, зашифровать можно только объекты MODX, потому что `EncryptedVehicle` наследует `xPDOObjectVehicle`, файлы и скрипты, добавленные через классы `xPDOFileVehicle` и `xPDOScriptVehicle` останутся без шифрования.

Получение пароля для шифровальщика

Отдельно стоит описать получение пароля для шифровальщика со стороны modstore.pro. Дело в том, что в инструкции описывается способ, который использует код из MODX, что в моем случае не подходит, так как пакет собирается только с использованием xPDO, без установки и использования кода MODX.

Чтобы получить пароль, требуется на адрес `modstore.pro/extras/package/encode`; отправить запрос POST с информацией о пакете и токенами авторизации. Опытным путем был получен минимальный список параметров, которые требуется отправлять в репозиторий для получения пакета:

$this->params = [
    'api_key' => '1h54gdtrr354',
    'username' => 'ivan@klimchuk.com',
    'http_host' => 'alroniks.com',
    'package' => 'foobar',
    'version' => '1.0.0-pl',
    'vehicle_version' => '2.0.0'
];

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

Когда пароль получен, требуется в скрипте сборки, перед первым использованием класса-шифровальщика, добавить константу `PKG_ENCODE_KEY`, которой присвоить полученный пароль. Эта константа будет использоваться в дальнейшем при шифровании элементов пакета.

define('PKG_ENCODE_KEY', $keyRequester->getKey());

Ссылка на полные примеры кода с подробными пояснениями в конце заметки.

Порядок действий

При наличии пароля зашифровать пакет легко, стоит просто указать в поле vehicle_class класс EncryptedVehicle. А вот правильная работа зашифрованного пакета при установке или обновлении зависит от соблюдения порядка выполнения действий в пакете. Как я уже говорил, действия в пакете выполняются в том порядке, в котором описаны в манифесте.

При попытке установить транспортный объект, MODX по имени класса типа объекта найдет у себя описание этого типа, создаст объект и выполнит метод `install` этого объекта. В случае трех встроенных типов проблем не возникнет, так как эти типы описаны в виде классов в xPDO. А вот в случае EncryptedVehicle получим ошибку, что такого класса нет. Чтобы это исправить, перед установкой элементов из пакета нужно этот класс добавить в MODX и загрузить.

В начале добавим файл с нашим классом в пакет через тип xPDOFileVehicle, а при установке файл будет скопирован в каталог нашего дополнения:

$package->put(new xPDOFileVehicle, [
    'vehicle_class' => 'xPDOFileVehicle',
    'object' => [
        'source' => 'encryptedvehicle.class.php',
        'target' => "return MODX_CORE_PATH . 'components/ourcomponent/';"
    ]
]);

Для MODX 2 версии важно, чтобы имя файла было в нижнем регистре и постфиксом class, иначе класс не будет найден загрузчиком классов MODX.

Затем при установке нужно класс из файла загрузить в MODX, иначе в системе будет болтаться бесполезный файл. Загрузку класса будем делать через скрипт на PHP:

$transport->xpdo->loadClass('transport.xPDOObjectVehicle', XPDO_CORE_PATH, true, true);
$transport->xpdo->loadClass('EncryptedVehicle', MODX_CORE_PATH . 'components/' . strtolower($transport->name) . '/', true, true);

А сам скрипт загрузим в пакет через тип xPDOScriptVehicle:

$package->put(new xPDOScriptVehicle, [
    'vehicle_class' => 'xPDOScriptVehicle',
    'object' => [
        'source' => 'resolve.encryption.php'
    ]
]);

За ними в пакет будут загружаться остальные элементы с уже зашифрованным содержимым. Вот тут и понадобится соблюдение порядка в манифесте и возможности дополнительных типов транспортных объектов. Файловый и скриптовый типы не шифруются, и выполнятся первыми, значит на момент установки зашифрованного объекта класса EncryptedVehicle, необходимый PHP класс уже будет загружен в MODX и доступен для использования.

Этот порядок требуется соблюдать в скрипте сборки, чтобы обеспечить правильную работу установщика. В каком порядке добавлять остальные элементы решайте самостоятельно.

Подводя итог

Подведем итог теории и кратко по шагам опишем действия, которые требуется выполнить, чтобы “защитить” свой пакет от посягательств.

• Добавить код получения пароля из modstore.pro в файл со скриптом сборки пакета. Используйте мой вариант, либо смотрите в оригинальной инструкции, где используется код из MODX.
• Скопировать файл с классом EncryptedVehicle к себе в пакет куда угодно в папку _build.
• В скрипте сборки в начале, после создания транспортного пакета, добавить транспортный объект типа xPDOFileVehicle с классом-шифровальщиком.
• Следом добавить транспортный объект типа xPDOScriptVehicle со скриптом, который этот класс зарегистрирует.
• Добавить собственные элементы, которые нужны в пакете и собрать пакет.

Что делать с modExtra

В первую очередь разобраться, как устроен скрипт сборки в этом компоненте. Код написан в виде класса, где функции логически и наглядно распределены по методам. Единственное различие, что для создания пакета используется функция `createPackage`, а для добавления транспортного объекта в пакет используется функция `putVehicle`. Найдите места, где эти функции используются и добавьте по примерам собственные объекты в пакет.

Для облегчения понимания механизма работы я приготовил пример простого и в меру бесполезного компонента FooBar (при установке создает одну системную настройку), где приведены файлы с подробными комментариями и пример распакованного архива компонента.

Надеюсь материал полезен.

Could not load class: encryptedVehicle from encryptedvehicle.