Порядок работы партнеров с сертификатами RSA 

1.Описание и цели

MTLS - Mutual TLS,  в переводе двухсторонний TLS или двухсторонний SSL, предоставляет возможность взаимной или двухсторонней аутентификации.

TLS - Transport Layer Security, протокол защиты транспортного уровня, основан на протоколе SSL (Secure Sockets Layer).

SSL - Secure Sockets Layer — уровень защищённых сокетов.

X.509 — стандарт ITU-T для инфраструктуры открытого ключа (Public key infrastructurePKI) и инфраструктуры управления привилегиями (Privilege Management Infrastructure). Формат сертификта X.509 определяет стандартные форматы данных и процедуры распределения открытых ключей с помощью соответствующих сертификатов с цифровыми подписями

По умолчанию протокол TLS только подтверждает идентичность сервера клиенту с помощью сертификатов X.509 , а аутентификация клиента на сервере остается на уровне приложений. Реализация MTLS позволяет обеспечить безопасный канал связи для вызова сервисов и выполнить аутентификацию не только сервера партнером, но и аутентификацию партнера с помощью сертификата X.509. Авторизация партнера производится на основе информации о партнере, указанной в сертификате. Информация из сертификата позволяет однозначно определить партнера и позволить получить доступ к вызову сервисов, при условии, что сертификат и его закрытый ключ не скомпрометированы.

Определение режима работы сервиса. Сертификат позволяет устанавливать для партнера режим работы сервиса (промышленный режим, когда запросы уходят в промышленную бизнес-систему Банка, или режим разработки, когда запросы уходят в тестовую инфраструктуру или возвращаются стандартные ответы заглушками сервиса)

Внимание! Работа mutual TLS на портале в Mozilla Firefox осуществляется некорректно из-за специфики браузера!

2. Требования к сертификату

Чтобы обеспечить проверку партнера на основе сертификата, в subject сертификата предусмотрены обязательные поля:

СountryName - Название страны партнера

Country - Страна, в виде двухсимвольного ISO-кода. Для России: RU

OrganizationName - Название организации

CommonName - ФИО представителя организации

EmailAddress - Электронный адрес для обратной связи

В зависимости от правовой формы указать одно из нижеперечисленных полей:

Для юридических лиц в России:

INN = 1.2.643.3.131.1.1

Для физических лиц в России:

SNILS = 1.2.643.100.3

Для иностранных партнеров:

FOREIGNID=1.3.6.1.4.1.16745.100.1

Для тестирования предусматривается общедоступный сертификат с нолями для ИНН, СНИЛС и FOREGNID. Этот сертификат позволяет протестировать сервисы на этапе разработки и внедрения, а также в рамках изменений. Сертификат можно скачать с сайта или получить от представителя банка. При возникновении вопросов и проблем с установкой сертификата необходимо обращаться в профильную поддержку по тому сервису, с которым возникают проблемы. Электронный адрес поддержки указан в документации API сервиса.

При указании электронного адреса необходимо помнить о том, что этот адрес будет использоваться при рассылке событий по сертификату (истечение срока, аннулирование и т.д.), поэтому рекомендуем указывать служебный адрес, а не персональный.

3.Порядок выпуска промышленного сертификата

Партнер согласовывает договорные отношения с Банком, на основе которых будет регулироваться работа партнера с банком, в том числе и порядок работы с сертификатом. Партнер посредством любого крипто-приложения создает закрытый ключ. Простейший вариант, в OpenSSL openssl genrsa -des3 -out name.key 2048. На основе созданного ключа партнер генерирует запрос сертификата (CSR) с приватным ключом RSA (на выходе будет получен PEM-формат) openssl req -new -key name.key -out name.csr Для проверки содержимого csr можно использовать команду: openssl req -noout -text -in name.csr Партнер передает запрос на сертификат любым способом, удовлетворяющим партнера. Закрытый ключ партнер строго хранит у себя и несет ответственность за его компрометацию! Со стороны банка Администратор на основе запроса выполняет выпуск сертификата, подписанного нашим CA и передает сертификат по оговоренным каналам связи в формате pem и pfx. Срок действия сертификата 375 дней.

4. Порядок повторного выпуска сертификата

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

5. Порядок использования сертификата

5.1. Партнер должен прописать содержимое сертификата в формате Base-64 в своем приложении.

Для этого на портале api.alfabank.ru партнер в главном меню необходимо зайти в приложения:

Затем зайти в свое приложение и нажать верхнюю правую метку «редактировать»:

В поле Certificate необходимо содержимое файла сертификата в формате Base-64

Затем необходимо нажать кнопку отправить.

5.2. Партнер должен прописать сертификат в своей среде.

Для windows систем сертификат устанавливается в личные. Самый простой вариант, вызвать файл PFX. Откроется мастер импорта сертификатов. Следуете указаниям, указываете пароль (для тестового сертификата пароль пустой). На этапе выбора хранилища указываете личное хранилище:

Порядок установки в рамках других систем должен быть описан в документации системы, в которой выполняется установка сертификата.

Ссылки на скачивание сертификата и закрытого ключа:

Тестовый сертификат в формате pfx

Тестовый сертификат в формате cer

Тестовый закрытый ключ

 

6. Пример CURL с использованием сертификата

curl -v --cert ./apidevelopers.cer: \

--key ./ apidevelopers.key \

--request GET --url https://apiws.alfabank.ru/alfabank/alfadevportal/ccretail/applications/C... \

--header 'accept: application/json' \

--header 'content-type: application/json' \

--header 'x-ibm-client-id: *************'

Также можно использовать для тестирования работы любое приложение, поддерживающее формирование REST запросов, например, postman:

Инструкция по формированию запроса в Postman

 

7. Пример генерации запроса на сертификат спомощью OpenSSL

Чтобы включить в OpenSSL поддержку полей ИНН и СНИЛС, их нужно добавить в настройки. Набор полей определяется в конфигурационном файле openssl.conf. Ниже приведены готовые секции для конфигурационного файла, при условии, что в системе стоят библиотеки для OpenSSL с поддержкой этих полей:

[ policy_match ]

countryName = optional

stateOrProvinceName = optional

organizationName = optional

#organizationalUnitName = optional

commonName = supplied

emailAddress = optional

INN = optional

SNILS = optional

FOREIGNID = optional

 

[ policy_anything ]

countryName = optional

#stateOrProvinceName = optional

localityName = optional

organizationName = optional

#organizationalUnitName = optional

commonName = supplied

emailAddress = optional

INN = optional

SNILS = optional

FOREIGNID = optional

 

[ req_distinguished_name ]

countryName = countryName

countryName_default = RU

countryName_min = 2

countryName_max = 2

stateOrProvinceName = State or Province Name (full name)

stateOrProvinceName_default = MSK

localityName = localityName

localityName_default = Moscow

0.organizationName = organizationName

0.organizationName_default = Alfa Bank

organizationalUnitName = Organizational Unit Name (eg, section)

organizationalUnitName_default = APIDeveloper

 

commonName = Common Name (eg, your name or your server\'s hostname)

commonName_max = 64

 

emailAddress = emailAddress

emailAddress_default = apisupport@alfabank.ru

emailAddress_max = 64

 

INN = INN

INN_def=0

 

SNILS = SNILS

SNILS_def=0

 

FOREIGNID = FOREIGNID

FOREIGNID_def = 0

 

 Если же библиотеки ГОСТ не стоят или же по каким-то причинам вернет ошибку, что не знает полей, то дополнительно в глобальную секцию прописать эти поля:

 # Individual insurance number (Numeric String)

INN = 1.2.643.3.131.1.1

SNILS = 1.2.643.100.3

OGRN = 1.2.643.100.1

FOREIGNID=1.3.6.1.4.1.16745.100.1

 

Чтобы не утратить дефолтный конфигурационный файл, на случай ошибок, при корректировке, лучше сохранить как отдельный файл с другим именем и его указывать при вызове через опцию -config.

 Порядок генерации:

1. Вначале генерируем закрытый ключ с паролем:

openssl genrsa -aes256 -out private/apidevelopers_pwd.key 2048

 2. Затем генерируем запрос на сертификат с интерактивным вводом данных:

openssl req -config openssl_01.cnf -key private/apidevelopers_pwd.key -new -sha256 -out csr/apidevelopers_pwd.csr