Документация BILLmanager 5
Документация
/
Документация BILLmanager 5
/
Разработчику
/
Создание модулей 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

Пример модуля

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

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

Использование заголовочных файлов BILLmanager для разработки собственных модулей обработчиков доступно с версии BILLmanager 5.58.0. Кроме приведенного упрощенного примера, можно изучить примеры представленные в пакете разработчика BILLmanager - billmanager-[Редакция BILLmanager]-devel:

yum install billmanager-corporate-devel
или
yum install billmanager-devel
Пояснения


После этого примеры можно найти в директории '/usr/local/mgr5/src/examples'

C++

Файлы:

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

Пример можно просмотреть онлайн — https://github.com/ISPsystemLLC/billmanager/

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

Для успешной сборки и установки модуля необходимо произвести следующие действия:

  1. Установить пакет:
    • Debian: apt-get install coremanager-dev
    • CentOS: yum install coremanager-devel
  2. Перейти в директорию: cd /usr/local/mgr5/src
  3. Получить исходники примера плагина:
    • Скачать их архивом нажав кнопку Download ZIP на странице https://github.com/ISPsystemLLC/billmanager. Развернуть и скопировать полученных файлы в директорию /usr/local/mgr5/src
    • Установить GIT. Debian: apt-get install. CentOS: yum install git. Клонировать репозиторий billmanager git clone https://github.com/ISPsystemLLC/billmanager
  4. Перейти в директорию: cd /usr/local/mgr5/src/billmanager/processing/certificate
  5. Собрать пример плагина make или собрать и установить make install