Подписание JSON ГОСТ-сертификатом

Способ защиты данных определяется настройками интеграции. Для уточнения информации по настройке Вашей интеграции или запроса для установления нужных настроек необходимо написать на почту alfa_api@alfabank.ru. При запросе установления настроек необходимо сообщить способ защиты (подпись или подпись с шифрованием), а также алгоритм (RSA или ГОСТ).

Внимание

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

Подписание JSON

Подготовить сообщение в формате JSON

Пример сообщения

{
  "sub": "1234567890",
  "name": "John Doe",
  "admin": true,
  "iat": 1657882689,
  "exp": 1657886289
}

Подписать запрос

Тело запроса сформировать алгоритмом ГОСТ Р 34.10-2012 256 бит в виде компактной сериализации в соответствии с JSON Web Signature и подписать тело запроса закрытым ключом сертификата.

Формат JWS

BASE64URL(UTF8(JWS Protected Header)) || '.' || BASE64URL(JWS Payload) || '.' || BASE64URL(JWS Signature)

Структура тела запроса

•
Заголовок (Header)
- •
  
  "alg": "GOST3410_2012_256"
- •
  
  "typ": "JWT"
- •
  
  "cty": "JWS"
- •
  
  "kid": "серийный номер сертификата"
- •
  
  "b64": true
•

JSON-документ (Payload)
•

Подпись запроса (Signature)

Пример JWS

ewogICJhbGciIDogIkdPU1QzNDEwXzIwMTJfMjU2IiwKICAidHlwIiA6ICJKV1QiLAogICJjdHkiIDogIkpXUyIsCiAgImtpZCIgOiAiNmQzOGI4ZTAwNjFiMGY5YTk0ZjEwNGJlNTdlNzdhYTE4IiwKICAiYjY0IiA6IHRydWUKfQ.eyJkZWJpdFR1cm5vdmVyIjp7ImFtb3VudCI6MCwiY3VycmVuY3lOYW1lIjoiUlVSIn19.ByCkNenTTtZQrnZplNOo9WyqPTxb6vFq0iExNHpuPCV6LUeXDFTe8tNBZCy1WvpdUCQBrKK447s3NJCC5hNLhA

Для тестовой проверки можно использовать https://token.dev/.

Выполнить запрос

Если добавить заголовки Content-Type: application/json + X-Request-ChannelSecurity: NO и отправить запрос, то подпись запроса не будет проверяться.

Если добавить заголовки Content-Type: application/jose + X-Request-ChannelSecurity: SIGNATURE и отправить запрос, то подпись запроса будет проверяться.

Если подпись валидна - запрос обрабатывается, если невалидна - Банк определяет запрос как неподлинный и возвращает ошибку.

Любые другие комбинации заголовков Content-Type + X-Request-ChannelSecurity приведут к ошибке.

Проверка подписи JSON

Получить ответ

Если добавить заголовки Accept: application/json + X-Response-ChannelSecurity: NO , то ответ не будет подписан.

Если добавить заголовки Accept: application/jose + X-Response-ChannelSecurity: SIGNATURE , то полученный ответ (в том числе ошибки) будет подписан и представлен в виде компактной сериализации.

Любые другие комбинации заголовков Accept + X-Response-ChannelSecurity приведут к ошибке.

Декодирование компактной сериализации JWS

JWS формируется из трёх составляющих и представляет структуру вида:

•

Base64URL(Header);
•

Base64URL(Payload);
•

Base64URL(Signature).

Пример JWS

Закодированный	Раскодированный
ewogICJhbGciIDogIkdPU1QzNDEwXzIwMTJfMjU2IiwKICAidHlwIiA6ICJKV1QiLAogICJjdHkiIDogIkpXUyIsCiAgImtpZCIgOiAiNmQzOGI4ZTAwNjFiMGY5YTk0ZjEwNGJlNTdlNzdhYTE4IiwKICAiYjY0IiA6IHRydWUKfQ.eyJkZWJpdFR1cm5vdmVyIjp7ImFtb3VudCI6MCwiY3VycmVuY3lOYW1lIjoiUlVSIn19.ByCkNenTTtZQrnZplNOo9WyqPTxb6vFq0iExNHpuPCV6LUeXDFTe8tNBZCy1WvpdUCQBrKK447s3NJCC5hNLhA	header `{ "alg": "GOST3410_2012_256", "typ": "JWT", "cty": "JWS", "kid": "6d38b8e0061b0f9a94f104be57e77aa18", "b64": true }` payload `{ "debitTurnover": { "amount": 0, "currencyName": "RUR" } }` verify signature `HMACSHA256( base64UrlEncode(header) + "." + base64UrlEncode(payload), )`

Проверить подпись ответа от Банка

Используйте открытый ключ сертификата Банка для проверки подписи. Для получения сертификата напишите на почту alfa_api@alfabank.ru.

Проверьте подпись в соответствии с данными, указанными в Заголовке (Header). В поле kid заголовка JWS будет записан серийный номер сертификата Банка.

Обработать ответ в формате JSON

Пример ответа

{
  "debitTurnover": {
    "amount": 0,
    "currencyName": "RUR"
  }
}