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

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

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

Команды модуля

Модули SSL-сертификатов представляют собой частный случай  модулей обработки услуг с itemtype name="certificate". Специфичные команды:

• approver;
• usercreate;
• reopen.

Модуль обрабатывает остальные команды (open, suspend, close, setparam, prolong, sync_item) по стандартному алгоритму для всех модулей обработки услуг.

Основные команды:

• open — создание услуги;
• suspend — приостановка услуги;
• resume — возобновление услуги;
• close — удаление услуги;
• setparam — изменение параметров услуги или смена тарифа;
• prolong — продление услуги;
• sync_item — синхронизация статуса услуги с внешней системой. Используется с параметром --item;
• check_connection — проверка параметров подключения к внешней системе;
• tune_connection — модификация формы добавления модуля обработки.

Дополнительные команды:

Специфичные команды для SSL-сертификатов:

• approver — получение email-адресов для подтверждения владения доменом;
• usercreate — создание аккаунта в центре сертификации;
• reopen — перевыпуск сертификата.

Пояснения к XML-файлу модуля SSL-сертификата

features — дополнительная секция <templates>

< doc >
< itemtypes >< itemtype name = "certificate" /></ itemtypes >
< params >...</ params >
< features >...</ features >
< templates >
< template name = "securesite" multidomain = "yes" orginfo = "yes" />
< template name = "wildcard" wildcard = "yes" www = "yes" />
</ templates >
</ doc >

Атрибуты: 

• multidomain;
• wildcard;
• www;
• orginfo;
• csraltname.

approver — выход

< doc >
< email >admin@example.com</ email >
< email >hostmaster@example.com</ email >
</ doc >

usercreate — вход и выход

Вход — принимает текущий XML-файл формы (стандартное описание формы BILLmanager).
Выход — возвращает изменённый XML-файл. Вы можете добавлять поля, атрибуты, подсказки.

check_param — вход и выход

Вход — принимает текущий XML-файл формы.

<doc>
<item> <!-- Список старых значений параметров услуги. -->
<param1>...</param1>
...
<paramN>...</paramN>
</item>
<newitem> <!-- Список новых значений параметров услуги. -->
<param1>...</param1>
...
<paramN>...</paramN>
</newitem>
</doc>

Выход — возвращает <doc/> или ошибку.

< doc >
< error type = "field" field = "altname" value = "Некорректный домен" />
</ doc >

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

Этапы работы с модулем SSL-сертификатов в BILLmanager:

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

Установите модуль:

• вручную, если он представлен набором файлов;
• из стандартного репозитория при помощи пакетного менеджера.

После установки модуль становится доступен для выбора при создании метода оплаты в BILLmanager.

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

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

Стандартный набор файлов модуля выглядит следующим образом:

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

Описание XML

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

<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">Свойство 2</msg>
      <msg name="hint_prop2">Подсказка для свойства 2</msg>
    </messages>
  </lang>
</mgrdata>

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

<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 — зарегистрировать аккаунт на стороне центра сертификации через интерфейс BILLmanager;
• check_connection — на вход модулю подаётся XML-документ с параметрами подключения к центру сертификации. Формат входного документа выглядит следующим образом:

<doc>
  <param>value</param>
  ...
  <param>value</param>
</doc>

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

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

<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 создаёт операцию. Если предыдущая попытка выполнения операции закончилась неудачей и включён автоматический перезапуск, 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 — код услуги.

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

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

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

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

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

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

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

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

Примеры модулей

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

С++

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

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

1. Подключитесь к серверу с платформой по SSH. Подробнее о подключении по SSH см. в статье Настройка рабочего места.
2. Установите пакет ПО:

apt-get install billmanager-corporate-dev

dnf install billmanager-corporate-devel

После установки содержимое пакета будет доступно в следующих директориях:

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

Пример содержит модуль интеграции с The SSL Store.

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

1. Подключитесь к серверу с платформой по SSH. Подробнее о подключении по SSH см. в статье Настройка рабочего места.

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

   Ubuntu, AstraLinux:

   apt-get install coremanager-dev

   AlmaLinux:

   dnf install coremanager-devel

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

   cd /usr/local/mgr5/src

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

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

        Ubuntu, AstraLinux:

        apt-get install git

        AlmaLinux:

        dnf install git

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

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

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

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

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

   Команда для сборки примера модуля

   make

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

   make install

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

   /usr/local/mgr5/sbin/mgrctl -m billmgr -R

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

Python

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

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

1. Подключитесь к серверу с платформой по SSH. Подробнее о подключении по SSH см. в статье Настройка рабочего места.
2. Установите пакет:

apt-get install billmanager-plugin-python-libs

dnf install billmanager-plugin-python-libs

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

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

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

1. Подключитесь к серверу с платформой по SSH. Подробнее о подключении по SSH см. в статье Настройка рабочего места.

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

   cd /usr/local/mgr5/src/

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

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

       Ubuntu, AstraLinux:

       apt-get install git

       AlmaLinux:

       dnf install git

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

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

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

   make globalsign

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

   /usr/local/mgr5/sbin/mgrctl -m billmgr -R

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