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

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

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

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

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

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

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

Секция 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 документ следующего вида:

<?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:

Получите тип задачи с помощью функции task.gettype. Передайте полученную модулем команду в функцию с помощью параметра operation.
Зарегистрируйте задачу с помощью функции 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 — неизвестный (не используется в 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 — метод подтверждения владения доменом, может принимать значения:
- auth_email — по email;
- auth_cname — по DNS CNAME записи;
- 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.

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

Установите пакет ПО:
Ubuntu 20.04, AstraLinux 1.7.4:
```
apt-get install coremanager-dev
```
CentOS 7, AlmaLinux 9:
```
yum install coremanager-devel
```
Перейдите в директорию:
```
cd /usr/local/mgr5/src
```
Получите исходники примера модуля. Это можно сделать двумя способами:
- Скачайте архив:
  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
```

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

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

Выполните команду:
команда для сборки примера модуля
```
make
```
команда для сборки и установки модуля
```
make install
```
Перезагрузите платформу:
```
killall core
```

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

Путь	Содержимое
processing/certificate/sslstore/dist/etc/xml/billmgr_mod_pmthesslstore.xml	XML-описание модуля обработки
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

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

Перейдите в директорию:
```
cd /usr/local/mgr5/src/
```
Получите исходники примера модуля. Это можно сделать двумя способами:
- Скачайте архив
  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
```
Выполните команду:
```
make globalsign
```
Перезагрузите платформу:
```
killall core
```

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

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