Документация BILLmanager 6 Startup, Advanced
Документация
/
Документация BILLmanager 6 Startup, Advanced
/
Разработчику
/
Создание модулей SSL-сертификатов

Создание модулей SSL-сертификатов

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

Общая информация

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

Механизм работы модуля

В общих чертах жизненный цикл модуля SSL сертификатов в BILLmanager выглядит следующим образом:

  1. Установка модуля
  2. Настройка подключения к центру сертификации
  3. Настройка тарифного плана
  4. Заказ и оплата услуги
  5. Обработка открытия услуги
  6. Включение/выключение/удаление услуги, а так же выполнение дополнительных операций

Установка модуля выполняется либо вручную, если он представлен набором файлов, либо из стандартного репозитария при помощи пакетного менеджера. После установки модуль становится доступен для выбора при добавлении подключения к центру сертификации в BILLmanager. Каждый модуль опрашивается BILLmanager на предмет поддерживаемых возможностей и списка необходимых параметров. Делается это один раз на один запуск BILLmanager при первом обращении к модулю. Делается это для ускорения работы BILLmanager исключив не поддерживаемые вызовы.

Структура модуля

Модуль SSL сертифакатов состоит из двух файлов:

  • etc/xml/billmgr_mod_XXX.xml — XML описание модуля. Формат наименования файла строго регламентирован;
  • processing/XXX - основной скрипт модуля. Формат наименования файла строго регламентирован.

Где XXX название вашего модуля, указываемое латиницей. Если название основного скрипта модуля содержит расширение файла, оно так же включается в имя модуля. Например, если ваш скрипт называется pmresellerclub.php, то именем модуля будет являться pmreselleclub.php, а не resellerclub или pmresellerclub.

Описание XML

Наименование файла должно иметь вид billmgr_mod_XXX.xml, где XXX — имя модуля. Файл копируется в каталог etc/xml относительно пути установки BILLmanager. Файл содержит описание самого модуля (описывается как плагин), а так же описание дополнительных форм и сообщений.

Примерный вид XML файла модуля:

<?xml version="1.0" encoding="UTF-8"?>
<mgrdata>
  <plugin name="XXX">
    <group>processing_module</group>
    <params>
      <type name="certificate"/>
    </params>
    <msg name="desc_short" lang="ru">XXX модуль</msg>
    <msg name="desc_short" lang="en">XXX module</msg>
    <msg name="desc_full" lang="ru">XXX модуль</msg>
    <msg name="desc_full" lang="en">XXX module</msg>
  </plugin>

  <metadata name="processing.edit.XXX" type="form">
    <form>
      <page name="connect">
        <field name="prop1">
          <input name="prop1" required="yes" type="text" />
        </field>
        <field name="prop2">
          <input name="prop2" required="yes" type="text" />
        </field>
      </page>
    </form>
  </metadata>

  <lang name="en">
    <messages name="label_processing_modules">
      <msg name="XXX">XXX module</msg>
      <msg name="module_XXX">XXX module</msg>
    </messages>

    <messages name="processing.edit.XXX">
      <msg name="prop1">Prop 1</msg>
      <msg name="hint_prop1">Hint for prop 1</msg>
      <msg name="prop2">Prop 2</msg>
      <msg name="hint_prop2">Hint for prop 2</msg>
    </messages>
  </lang>

  <lang name="ru">
     <messages name="label_processing_modules">
      <msg name="XXX">XXX модуль</msg>
      <msg name="module_XXX">XXX модуль</msg>
    </messages>

    <messages name="processing.edit.XXX">
      <msg name="prop1">Свойство 1</msg>
      <msg name="hint_prop1">Подсказка для свойства 1</msg>
      <msg name="prop2">Свойствоop 2</msg>
      <msg name="hint_prop2">Подсказка для свойства 2</msg>
    </messages>
  </lang>
</mgrdata>

Здесь секция <plugin> - отвечает за описание самого модуля. Свойство name совпадает с именем модуля заказа SSL сертификатов. Внутри секции может быть один элемент group со значением processing_module, который указывает на то, что данный модуль используется для обработчиков услуг, несколько элементов msg и секция params с поднодой <type name="certificate"/>, указывающий на то что обработчик относится к модулям заказа SSL сертификатов, т.е. умеет обрабатывать услуги с типом имеющем внутреннее имя certificate. Свойство lang у элемента msg указывает к какому языку относится сообщение, атрибут name может иметь следующие значения:

  • desc_short — краткое описание модуля. Отображается при выборе модуля в BILLmanager;
  • desc_full — полное описание модуля. Отображается при построение списка на форме добавления обработчиков услуг в BILLmanager.

Секция metadata с именем processing.edit.XXX отвечает за дополнительные поля модуля при добавлении и настройке обработчика. Формируется согласно стандартному описанию XML формы, с учетом необходимости расположения полей в секции <page name="connect"></page> для корректного размещения полей на формах в BILLmanager.

Секция lang содержит переводы наименований полей на форме согласно стандартной схеме описания переводов. Раздел <messages name="label_processing_modules"> отвечает за подпись наименования модуля в списке обработчиков.

Основной скрипт модуля

Основной скрипт модуля оплаты отвечает за передачу BILLmanager информации о поддерживаемых модулем функциях, а так же обработку этих функций. При работе с модулем BILLmanager исполняет файл скрипта со следующими параметрами:

processing/pmxxx --command command [--item item] [--module module] [--itemtype itemtype] [--param param --value value] [--runningoperation runningoperation] [--domain domain]

Где

  • command — управляющая команда. Указывает на действие, которое необходимо выполнить модулю;
  • item — код услуги, для которой выполняется действие;
  • module — код обработчика, для которого выполняется действие;
  • itemtype — внутреннее наименование типа продукта, для которого выполняется действие;
  • param — наименование параметра;
  • value — значение параметра;
  • runningoperation — код текущей операции для выполняемого действия. Требуется для изменения параметров текущей операции, а так же для создания задач;
  • domain — наименование домена, для которого выпускается сертификат.

Параметр runningoperation передается если модуль запущен BILLmanager после создания текущей операции. По завершению работы модуля в этом случае нужно либо выполнить одну из функций BILLmanager (описаны далее в статье), которая удалит текущую операцию из очереди, либо выполнить одно или несколько из следующих действия:

  • сохранить текст ошибки в свойствах текущей операции с помощью функции runningoperation.edit
  • выставить текущей операции ручной запуск, для предотвращения автоматического перезапуска данной операции с помощью функции runningoperation.setmanual
  • создать задачу на ответственный отдел с помощью функции task.edit

Параметр command может принимать одно из следующих значений:

  • features — запрос списка поддерживаемых возможностей. В ответ на вызов данной команды модель должен вернуть XML документ следующего вида:
<?xml version="1.0" encoding="UTF-8"?>
<doc>
 <itemtypes>
    <itemtype name="certificate"/>
 </itemtypes>
 <params>
    <param name="url"/>
    <param name="auth_token" crypted="yes"/>
    <param name="partner_code"/>
 </params>
 <features>
    <feature name="check_connection"/>                                 <!-- поддержка модулем функции проверки введенных при добавлении обработчика услуг параметров -->
    <feature name="approver"/>                                         <!-- поддержка модулем функции получения списка email-адресов администратора -->
    <feature name="prolong"/>                                          <!-- поддержка продления услуг на стороне центра сертификации -->
    <feature name="usercreate"/>                                       <!-- поддержка модулем функции создания аккаунта центра сертификации -->
    <feature name="sync_item"/>                                        <!-- поддержка получения информации о сертификате от центра сертификации -->
 </features>
 <templates>
    <!-- Список поддерживаемых сертификатов: -->
    <template name="securesiteproev" multidomain="yes" orginfo="yes"/>
    <template name="securesitewildcard" wildcard="yes" orginfo="yes"/>
    <template name="quicksslpremium" www="yes"/>
    <template name="truebizid" orginfo="yes" csraltname="yes"/>
    ...
    <!--
    Свойства сертификатов: 
    multidomain - сертификат с поддержкой альтернативных доменных имён
    orginfo - сертификат требует указания информации о организации
    wildcard - сертификат выдаётся на все поддомены *.mydomain.com
    www - сертификат выдаётся на domain.com и www.domain.com
    
    Способы подтверждения владения доменом:
    authemail - по email;
    authcname - через DNS CNAME;
    authfile - по HTTP(S).
    -->
  </templates>
</doc>

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

  • approver — запрос списка разрешенных email-адресов администратора.
  • usercreate — зарегистрировать аккаунт на стороне центра сертификации через интерфейс BILLmamanger.
  • check_connection — на вход модулю подается XML с параметрами подключения к центру сертификации. Формат входного документа выглядит следующим образом:
<?xml version="1.0" encoding="UTF-8"?>
<doc>
  <param>value</param>
  ...
  <param>value</param>
</doc>

Независимо от требований модуля параметры представлены в не зашифрованном виде.

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

<?xml version="1.0" encoding="UTF-8"?>
<doc/>
  • tune_connection — на вход обработчику передается XML документ текущего описания формы подключения к центру сертификации, на выход нужно передать либо XML документ с необходимыми изменениями
  • open — команда открытия услуги. Модулю так же передаются параметры item и runningoperation (при запуске задания BILLmanager). По завершению обработки открытия услуг необходимо вызвать функцию certificate.open для завершения обработки услуги и удаления задания из текущих операций.
  • reopen — команда перевыпуска SSL сертификата. Модулю так же передаются параметры item и runningoperation (при запуске задания BILLmanager). По завершению обработки открытия услуг необходимо вызвать функцию service.postreopen для завершения обработки услуги и удаления задания из текущих операций.
  • suspend — команда выключения услуги. Модулю так же передаются параметры item и runningoperation (при запуске задания BILLmanager). По завершению выключения услуги необходимо вызвать функцию service.postsuspend для перевода услуги в статус Остановлена и удаления задания из текущих операций.
  • resume — команда включения услуги. Модулю так же передаются параметры item и runningoperation (при запуске задания BILLmanager). По завершению включения услуги необходимо вызвать функцию service.postresume для перевода услуги в статус Активна и удаления задания из текущих операций.
  • close — команда удаления услуги. Модулю так же передаются параметры item и runningoperation (при запуске задания BILLmanager). По завершению удаления услуги необходимо вызвать функцию service.postclose для перевода услуги в статус Удалена и удаления задания из текущих операций.
  • setparam — команда изменения параметров или тарифа услуги. Модулю так же передаются параметры item и runningoperation (при запуске задания BILLmanager). По завершению изменения параметров услуги необходимо вызвать функцию service.postsetparam для сохранения нового тарифного плана, обновления стоимости услуги для отображения в списке и удаления задания из текущих операций.
  • prolong — команда продления срока действия услуги. Модулю так же передаются параметры item и runningoperation (при запуске задания BILLmanager). По завершению продления услуги необходимо вызвать функцию service.postprolong для удаления задания из текущих операций.
  • sync_item — команда получения информации об услуге от центру сертификации. Модулю так же передается параметр item. Сохранение параметров выполняется с помощью функций certificate.save описанной ниже. В случае ошибки выпуска сертификата сообщить об этом клиенту можно функцией certificate.failed
  • check_param — команда проверки параметров услуги при их изменении. Модулю передаются параметры item — код услуги, param — имя параметра (передается только для некоторых встроенных параметров), value — значение параметра (передается только для некоторых встроенных параметров), level — уровень доступа пользователя, изменившего параметры. На вход модулю так же подается XML содержащая прежние и новые значения параметров услуги.

Пример реализации скрипта можно найти в конце статьи

Структура связанных таблиц

  • таблица item — содержит основную информацию об услугах, поле id — код услуги, поле processingmodule — код обработчика
  • таблица certificate — содержит данные сертификата, поле item — код услуги, поле csr — текст запроса на выпуск сертификата
  • таблица processingmodule — содержит основную информацию об обработчике услуг, поле id — код обработчика
  • таблица processingparam — содержит параметры модуля обработчика, поле processingmodule — код обработчика, intname — имя параметра, value — значение
  • таблица processingcryptedparam — содержит зашифрованные параметры модуля обработчика, поле processingmodule — код обработчика, intname — имя параметра, value — зашифрованное значение

Работа с текущими операциями

Перед передачей большинства запросов модули BILLmanager создает операцию, которая будет перезапущена, в случае если предыдущая попытка закончилась неудачей и если включен автоматический перезапуска. Код операции передается в модуль параметром runningoperation и может отсутствовать.

Если модулем получен код текущей операции, то в случае ошибки обработки команды можно сохранить информацию о ней в параметрах текущей операции для отображения в BILLmanager с помощью функции runningoperation.edit, а так же перевести ее запуск в ручной режим с помощью функции runningoperation.setmanual.

В случае если вы так же хотите создать задачу на основе текущей операции, для ее решения администратором BILLmanager вам необходимо:

  1. Получить тип задачу с помощью функции task.gettype передав в нее параметром operation полученную модулем команду
  2. Зарегистрировать задачу с помощью функции task.edit

После этого задача появится в списке у сотрудников входящих в отдел выбранный в качестве ответственного в настройках обработчика.

Функции BILLmanager

  • paramlist — не требует параметров. Отдает список параметров конфигурации панели
  • runningoperation.delete — удаление текущей операции
    • elid — код текущей операции
  • runningoperation.edit — изменение параметров текущей операции
    • elid — код текущей операции
    • sok=ok — признак сохранения параметров
    • errorxml — XML произошедшей ошибки
  • runningoperation.setmanual — перевести текущую операцию в режим ручного запуска
    • elid — код текущей операции
  • certificate.open — операция завершения открытия услуги. Меняет статус услуги на "активен", отправляет клиенту письмо о завершении обработки услуги и удаляет операцию на открыти
    • elid — код услуги
    • sok=ok — признак сохранения параметров
  • service.postclose — операция завершения удаления услуги. Меняет статус услуги и удаляет операцию на удаление
    • elid — код услуги
    • sok=ok — признак сохранения параметров
  • service.postopen — операция завершения открытия услуги. Только удаляет операцию на открытие услуги
    • elid — код услуги
    • sok=ok — признак сохранения параметров
  • service.postreopen — операция завершения перевыпска SSL сертификата. Только удаляет операцию на перевыпуск сертификата
    • elid — код услуги
    • sok=ok — признак сохранения параметров
  • service.postprolong - операция завершения продления услуги. Только удаляет операцию на продление услуги
    • elid — код услуги
    • sok=ok — ризнак сохранения параметров
  • service.postresume - операция завершения включения услуги. Меняет статус услуги и удаляет операцию на включение
    • elid — код услуги
    • sok=ok — признак сохранения параметров
  • service.postsetparam — операция завершения изменения параметров услуги. Сбрасывает ссылку на предыдущий тарифный план, удаляет текущую операцию и обновляет стоимость услуги для отображения в списке
    • elid — код услуги
    • sok=ok — признак сохранения параметров
  • service.postsuspend — операция завершения выключения услуги. Меняет статус услуги и удаляет операцию на выключение
    • elid — код услуги
    • sok=ok — признак сохранения параметров
  • service.saveparam — сохраняет произвольный параметр услуги
    • elid — код услуги
    • name — внутреннее имя параметры
    • value — значение параметра
  • service.setexpiredate — изменяет срок действия услуги
    • elid — код услуги
    • expiredate — новый срок действия услуги
  • service.setstatus — меняет дополнительный статус услуги
    • elid — код услуги
    • service_status — новый статус услуги
  • certificate.save — сохраняет данные выпущенного сертификата в BILLmanager
    • elid — код услуги
    • crt — данные сертификата
    • crt_type — тип данных сертификата. Пустое значение для текстового представления сертификата. При сохранении в панели архива, передается тип (расширение файла) архива, а содержимое файла передается в кодировке base64
  • certificate.failed — сохраняет данные выпущенного сертификата в BILLmanager
    • elid — код услуги

Статусы услуги

Дополнительный статус услуги может принимать следующие значения:

  •  — неизвестный (не используется в 5й версии)
  • 1 — заказан не оплачен (не используется в 5й версии)
  • 2 — оплачен не обработан (не используется в 5й версии)
  • 3 — запрос на сертификат отправлен
  • 4 — сертификат ожидает выпуска
  • 5 — сертификат выпущен
  • 6 — ошибка при оформлении сертификата

Дополнительные параметры услуги

  • altname — альтернативные домены для SAN сертификатов
  • old_altname — прежний список альтернативных имен. Сохраняется в базе данных в случае перевыпуска SSL сертификата с изменением списка альтернативных доменов для SAN сертификатов
  • approver_email — email адреса для подтверждения владения доменом, указанным в сертификате
  • custom_order_id — код сертификата на стороне центра выпуска сертификатов
  • service_status — текущий дополнительный статус услуги
  • approver_method — метод подтверждения владения доменом, может принимать значения:
  1. auth_email — по email;
  2. auth_cname — по DNS CNAME записи;
  3. auth_file — по HTTP(S).

Особенности обработки SAN сертификатов

Обработка SAN сертификатов практически идентична обработке других типов сертификатов с двумя дополнениями:

  • Список email адресов подтверждения владения доменов хранится в одном параметре approver_email. Адреса перечисляются через запятую в том же порядке, что указаны дополнительные домены. При этом email адрес подтверждения основного домена всегда указан первым
  • При обработке перевыпуска SSL сертификатов нужно обратить внимание на параметр услуги old_altname. Если он не пуст, используется перевыпуск сертификата с изменением списка дополнительных доменов. При этом новый список доменов хранится в параметре altname, список доменов указанный до перевыпуска - в параметре old_altname

Пример

На github есть примеры модулей обработки на С++ и Python. Примеры доступны по ссылке https://github.com/ISPsystemLLC/billmanager/

С++

C++ (с использованием библиотек BILLmanager)

Кроме приведенного примера, вы можете изучить примеры из пакета разработчика BILLmanager. BILLmanager содержит библиотеки, необходимые для работы модулей на С++. Для разработки собственных модулей обработчиков установите пакет:

для BILLmanager Corporate, Hosting&Cloud
yum install billmanager-corporate-devel

После установки:

ПутьСодержимое
/usr/local/mgr5/include/billmgr/библиотеки для разработки
/usr/local/mgr5/src/examples/примеры модулей

/usr/local/mgr5/src/template/xml/

примеры xml файлов

Пример модуля интеграции с The SSL Store на С++

В примере представлен рабочий модуль интеграции с The SSL Store.

Для сборки и установки модуля:

  1. Установите пакет ПО:

    Ubuntu 20.04, AstraLinux 1.7.4:
    apt-get install coremanager-dev
    CentOS 7, AlmaLinux 9:
    yum install coremanager-devel

  2. Перейдите в директорию:

    cd /usr/local/mgr5/src
  3. Получите исходники примера модуля. Это можно сделать двумя способами:
    • Скачайте архив:
      1. Перейдите на страницу https://github.com/ISPsystemLLC/billmanager
      2. Нажмите Code → Download ZIP. Архив с примером будет скачан на ваш ПК.
      3. Разархивируйте и скопируйте полученные файлы в директорию /usr/local/mgr5/src/.
    • Создайте локальную копию репозитория:

      1. Установите GIT:

        Ubuntu 20.04, AstraLinux 1.7.4:
        apt-get install git


        CentOS 7, AlmaLinux 9:
        yum install git

      2. Клонируйте репозиторий BILLmanager:

        git clone https://github.com/ISPsystemLLC/billmanager

  4. Перейдите в директорию:

    cd /usr/local/mgr5/src/billmanager/processing/certificate/sslstore/

  5. Выполните команду:

    команда для сборки примера модуля
    make
    команда для сборки и установки модуля
    make install

  6. Перезагрузите платформу:

    killall core

После установки файлы с примером модуля будут расположены в директории /usr/local/mgr5/src/billmanager/.

ПутьСодержимое
processing/certificate/sslstore/dist/etc/xml/billmgr_mod_pmthesslstore.xmlXML-описание модуля обработки
processing/certificate/sslstore/pmthesslstore.cppосновной файл модуля
processing/certificate/sslstore/common.hописание типов перечисления для работы с BILLmanager
processing/certificate/sslstore/defines.hопределение различных макросов
processing/certificate/sslstore/module.hописание классов для создания модулей обработки BILLmanager
processing/certificate/sslstore/module.cppреализация классов для создания модулей обработки BILLmanager
processing/certificate/sslstore/sslutil.hописание классов для создания шаблонов SSL-сертификатов
processing/certificate/sslstore/sslutil.cppреализация классов для создания шаблонов SSL-сертификатов
processing/certificate/sslstore/util.hвспомогательные функции для работы с BILLmanager

Python

Модуль интеграции на Python доступен с версии BILLmanager 6.75.0.

Для работы модулей обработчиков на Python и разработки собственных установите пакет:

Ubuntu 20.04, AstraLinux 1.7.4:
apt-get install billmanager-plugin-python-libs
CentOS 7, AlmaLinux 9:
yum install billmanager-plugin-python-libs

В директорию lib/python/billmgr/ будут установлены:

Файл модуляОписание
config.pyмодуль для работы с параметрами конфигурационного файла BILLmanager
misc.pyмодуль для взаимодействия с BILLmanager через работу с утилитой mgrcrl
logger.pyмодуль логирования
db.pyмодуль для работы с базой данных BILLmanager
crypto.pyмодуль для работы с хэшированием, RSA-шифрованием, CSR-запросами
exception.pyмодуль исключений в формате BILLmanager

Пример модуля интеграции GlobalSign на Python

Для сборки и установки модуля вы можете воспользоваться одним из предложенных способов:

  1. Перейдите в директорию:

    cd /usr/local/mgr5/src/
  2. Получите исходники примера модуля. Это можно сделать двумя способами:
    • Скачайте архив
      1. Откройте страницу https://github.com/ISPsystemLLC/billmanager.
      2. Нажмите Code → Download ZIP. Архив с примером будет скачан на ваш ПК.
      3. Разверните и скопируйте полученные файлы в директорию /usr/local/mgr5/src.
    • Создайте локальную копию репозитория:

      • Установите GIT:

        Ubuntu 20.04, AstraLinux 1.7.4:
        apt-get install git
        CentOS 7, AlmaLinux 9:
        yum install git

      • Клонируйте репозиторий BILLmanager:

        git clone https://github.com/ISPsystemLLC/billmanager

  3. Выполните команду:

    make globalsign

  4. Перезагрузите платформу:

    killall core

После установки файлы с примером модуля будут расположены в директории /usr/local/mgr5/.

ПутьСодержимое
etc/xml/billmgr_mod_pmglobalsign.py.xmlXML описание модуля обработки
processing/pmglobalsign.pyосновной файл модуля