Использование программного компонента#

В данном разделе представлена информация об отправке POST-запроса для Istnomnia через утилиту cURL.

Описание механизма шифрования#

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

• приватный ключ;

• публичный ключ.

При отправке писем АС шифрует данные, а программный компонент расшифровывает их. Приватный ключ используется для шифрования и должен храниться в секрете на стороне программного компонента. Публичный ключ используется для дешифрования и может свободно передаваться и использоваться на стороне АС. Вектор шифрования представляет собой случайно-сгенерированную строку. Его цель — обеспечить уникальность шифра при шифровании одинаковых данных с одним и тем же ключом, чтобы предотвратить выявление закономерностей и повысить безопасность. Вектор шифрования обычно передается вместе с зашифрованным сообщением.

Программный компонент на своей стороне генерирует пару из приватного и публичного ключа с помощью стандартных утилит (например, openssl, keytool). Далее публичный ключ передаётся АС.
Для шифрования используется алгоритм «AES/GCM/NoPadding»

Приватный ключ программного компонента хранится в секрете на стороне программного компонента в JKS-файле в SecMan. Публичный ключ программный компонент хранится на стороне АС

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

Для расшифрования данных АС использует 3 компонента:

• зашифрованные данные;

• вектор, который передал программный компонент;

• собственный приватный ключ.

Для расшифрования можно использовать стандартные библиотеки.

Описание параметров запроса#

Информация об отправке запроса через Insomnia описан в разделе «Быстрый старт» документа «Руководство прикладного разработчика».

Формат запроса зависит от включенного флага «Требуется ли шифрование тела и темы письма?» на почтовом ящике, добавленного в UI программного компонента.

Отправка запроса через cURL с выключенным флагом шифрования#

Для отправки запроса потребуется:

• приватный ключ сертификата клиента;

• публичный сертификат клиента;

• сертификат(-ы) Удостоверяющего центра для проверки сертификата вызываемого сервиса;

• Примечание: Создание ключа и выпуск сертификата не регламентируется. Утилиту cURL можно скачать с ресурса: https://curl.se/download.html

Запрос#

Заголовки

Тело запроса

Пример:

curl --request POST https://${host}/send \
    -H "Content-Type: application/json;charset=UTF-8" \
    -H "Email-From: mail@example.com" \
    -d '{
            "messageId": "test_unique_message_id"
            "bodyType": "text/plain",
            "importance": "high",
            "to": ["mail@example.com"],
            "subject": "Just subject",
            "secret": "mailbox_token",            
            "body": "Just body",
        }' \
    --cacert rootCA.crt \
    --key client.key \
    --cert client.crt

Описание параметров

Ответ#

Пример:

{
  "code": -1,
  "message": "Ошибка обработки запроса",
  "timestamp": "2022-09-29T14:14:20.435",
  "data": {
    "description": "Ошибка",
    "explanation": "Ошибка парсинга запроса; Неверный ID почтового ящика",
    "transactionId": "DBB7EC132EBA408F8FB3389C18D0D416",
    "messageId": "${messageId}"
  }
}

Параметры ответа:

Отправка запроса через cURL со включенным флагом шифрования#

Если флаг шифрования включен, то программный компонент перед обработкой запроса будет производить расшифровку темы и тела письма. АС-отправитель должен зашифровать тему и тело запроса ключом и вектором инициализации.

Запрос#

Заголовки запроса соответствуют заголовкам, указанным в формате с выключенным флагом шифрования (см. выше).

В тело запроса добавляются следующие поля:

Ответ#

Формат ответа такой же, как с выключенным флагом шифрования (см. выше).