B2BB2CH2H

Шифрование JSON RSA-сертификатом

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

Подписание и шифрование JSON
1

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

Пример сообщения 
{
  "sub": "1234567890",
  "name": "John Doe",
  "admin": true,
  "iat": 1657882689,
  "exp": 1657886289
}
2

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

Тело запроса сформировать алгоритмом RS256 в виде компактной сериализации в соответствии с JSON Web Signature и подписать тело запроса закрытым ключом сертификата, выпущенным в сервисе "Электронная подпись".

Формат JWS

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

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

  • •
    Заголовок (Header)
    • •
      "kid": "серийный номер сертификата"
    • •
      "typ": "JWT"
    • •
      "alg": "RS256"
  • •
    JSON-документ (Payload)
  • •
    Подпись запроса (Signature)

Пример JWS

eyJhbGciOiJSUzI1NiIsImtpZCI6IjYxMDAwMzYzY2NiNzU5Y2I0NDg2MDc4NjVkMDAwMTAwMDM2M2NjIn0.eyJzdWIiOiIxMjM0NTY3ODkwIiwibmFtZSI6IkpvaG4gRG9lIiwiYWRtaW4iOnRydWUsImlhdCI6MTY1Nzg4MjY4OSwiZXhwIjoxNjU3ODg2Mjg5fQ.ApKNzZ9kLMtBY3LzReSHQ7_AyDnzocGo9GTQFRmxTiRS7Lj7a55Kr4ziwZAmmwloF1063JJMOaU0lS947q6_hSct9pxzPdZ9tTmpIDGnQL-ks0oB7zz9vUSUd3G00UZXSYnuhI9BBRXvmmTaue5Y2j5zVZofLdO2dqPWCnsQULyLn_vYf8PeABhnAQ29z1Bq42uxfRFTM35cF40Tp4VBSqXDI1vxfleLusQlOZM-5Sk7O3Vy4Sf-UB03RrRGSBerZjdoMRh7dgEyoYAXS6c4MejCm2vmXKqSd7pu2V2TxOM9UTchkCS16DL-RIJtnfMjznmznU5SoMCpncvs6gRNeQ

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

3

Зашифровать запрос

Преобразуйте полученный на шаге два JWS-контейнер алгоритмом RS256 в соответствии с JSON Web Encryption и зашифруйте открытым ключом сертификата.

Формат JWE

BASE64URL(UTF8(JWE Protected Header)) || '.' || BASE64URL(JWE Encrypted Key) || '.' || BASE64URL(JWE Initialization Vector) || '.' || BASE64URL(JWE Ciphertext) || '.' || BASE64URL(JWE Authentication Tag)

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

  • •
    Заголовок (Protected Header)
    • •
      "kid": "серийный номер сертификата"
    • •
      "enc": "A256GCM"
    • •
      "alg": "RSA-OAEP-256"
  • •
    Ключ шифрования (Encrypted Key)
  • •
    Вектор инициализации (Initialization Vector)
  • •
    JSON-документ в зашифрованном виде (Payload)
  • •
    Тег аутентификации (Authentication Tag)

Пример JWE

eyJlbmMiOiJBMjU2R0NNIiwiYWxnIjoiUlNBLU9BRVAtMjU2In0.eFcY1Fv_xN6cFDNxnMoxCjEpVTmAjhrHuB2oW1hYapBXE02qOtdKrC3W7FGVjLFlgV3-OnAiOUaFUguYYtMbBMTsn5huQDSDgC4uvKjjSLSXfEtLCdSYHaMsMd7bov70BmHUmb0LscfIFB6CKqu56SAFQf3Aoqc0LAqMjpXxo4oK3XYZz61oekJP8r5dReXmKUbNWMG49c-JBeKJWMWiZDARIkKEOGF9fXe8x7O7ZFuiSbTa_y9OCVmkX6hDgIp5wgmH4ZDMybDE9woPVSU-MYRaY1TdPH3ovE73bBJHUiElPMdDZ9d5li9bvc7Wj_YBbsmvu5kcn02qSGSx4JTfckqQchcJmmOt2KHQX8Rx-FqQIWBeMXtZW-ivmwFbeoyJHsX6x3BGbesWOB8JUuff26eJyv77P1SKWCEujAfi_pQwkMaN7mo5iHUxk1msnzw3OMl96tqVKlzeYxzgAw2r7aNed6QEAGrK9aDqU8r2yPn3ALG4tOKmkhvu1kv3vniGjObRXfn_8o21nnoCpCl15MZmysI_NNwS4lTn2K6JpO-XuIII2w7YNX7fxFvgXn85NCYXSDUwekjlLiCUBeJTKastbnEaOmdZp73_PP8xJx45nHoIi1APNs3BFjP-wtt2UGn1rB50oDWS2YZdXe-H0a3_a2EiUlCbnWA9PiIn3wM.d_BoXT0XdgLEptKv.3GfMQkRp31TdhFZkj5nH387urf4AKDAs7NF-1mu_trY0eJowy4B0ocunnYjrXweUJYaddzN45cMeLpBCP_1JWImK926JpJTGrih5NsixyMp4hJ6ckmsMvUHwLGzp385ntDMuYCtExWDNxoL28oPK_MY2ga2mydu8RjVrYLRqjsn__o27aq0_wqNpbEh7ZbJ9AnCCMS5G02iKmFRhF8MX6eSrXcirUimljjQyKvX1TrZck3j3uIc5R406DdiKzsyQUT7PtyGrQU_FYbFSV5T7-OwnbTog1XUuVjy2vc1ryZ3WCe2g8fiRBNVnqSNNCfkzC75O3raS25tQRme70gM4t5YdQqp5oOs6DZ8QckuGIXILeRxZjDBjXB6DzfNgaXDXI1bWpjz_CrKpLoOYj_sVeDsCMQiGrV3yWWQkA1lSx_8pBG9oqqp-GY0B-Q_9xKcwooskI74xwdDHn1YitBriQs9bqYKKpciebaGDy5G8-Dk7PHB7ECL1aiDz4F8nthT-cQGkvX1niUpfFFn28S1-fc2l1noKspM4HnvDpk3EUOApBswVjKHlnHrERD2XXblBcrT8zIuLQiGuZewqA8i2-EDKjq0V4ckj8VR7a8eselpjdDk59Ru0ncLBfLvGS6g-E3xUqWj3rLG-Qx0WRN6svxEwfRxkuaxLDjeXTOWtIGu6C13jRIZScsGU30w.ZfAY-M8w-t9l9gErE1vQFg

4

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

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

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

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

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

Дешифрование и проверка подписи JSON
1

Дешифровать ответ

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

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

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

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

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

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

  • •
    Base64URL(Protected Header) - не зашифровано;
  • •
    Base64URL(Encrypted Key) - зашифровано;
  • •
    Base64URL(Initialization Vector) - зашифровано;
  • •
    Base64URL(Ciphertext) - зашифровано;
  • •
    Base64URL(Authentication Tag) - зашифровано.

Пример JWE

Закодированный Раскодированный
eyJlbmMiOiJBMjU2R0NNIiwiYWxnIjoiUlNBLU9BRVAtMjU2In0.WQr-wviYOnJOZvnTxCNgc2F1Km07ZvPTEd60PtKJkozmhNR2rSDo0bkVyMPlJNoy2U2ZEejnhJdWy7dZm467vmUa0dZWHiDDvaWWdHJfiTt7EUbTFll3dzCFGILpyinRxfqkBM94IYWjQBmxmru8aECGPI3j8375prZIPUgk7B0CgALTk-bejBcYkE2Gy2FOPUymetdJSHJrw1NCJXHZkrExdkz7AsQlo3or43NOq6x9F1I7QSUVxA-COuT4ENK-r0ek1Hfd0axc5GQTc8Qj0PJcA-tf4x_eet9z1aUG6zEKCOONWVZ5Ffd0JTbCmL-qvIYo0_7ZRTxenbzWt2psBw.GuBg7uZmEHn4f-PX.cd5vtMGwlupieD0S9JOA5zXIrk9d38NMg1ibWYRuHmkxMg9TjALzvG47lv6gZS04NnjKKaqWtxBFz95DNExL84PadeOO24CIHJOboEgUNsVpLPSl0FIubSaXnkkq5YEKK2j_eeYD2jvNwg10svlVnqeH3U-hbM096Rl2Wpow4jnw4sIs3e18TKE_nVUMk1IWi9Qm9aQvaK3z_Cx9DrDVpK63L96Zreh_DolilBn4NnnKxJpdvex_AqvVrg8QUgNl92ju9zewaMs9fMaNc0QpQUgPygcGLsHX1p9k7mHHOqv4b5mpRpPTu_Zb2p9Xjwps0ZnjTERefA25xwxa4ng7YsaYk1JbYLtpGbaZC_11_-Dh1WLPH5MUQDoJhQ3gIEFea4J8YLKHZN1eJIJGTBucCfoDLx2NrtZpH89LUXXDy3OnLLaHzSjr68xpJ0NsI5-_h8sCoYwxu5mPxdQXqSeMlw6gZHajBsNWPLc75d8w04JFnBLQXjYdLqzKG6P_7Cheht8pj4FycjGelE38RbZrw8897Cw7lPAaY9PERRvBHHVfZWow9ZWk5qrGP-RBshUcT2ZG6YIFCCVtftH8zaHZVXs9ykReBC12H6_CHXoDQyoZNYnMTXEuB-MgQYrq1smxIdhijKXaxkj8rCsx1cHLpfAureLh2e2M8anpFDVOsrm_d9TF-BjkAFjheKqKbEAqRN57ZF10UesP98QNZDOsvk-8zNAf_EOKDIsZ5xU.BNe9it8DGmlrYzcZoMEn8w
protected header 
{
  "enc": "A256GCM",
  "alg": "RSA-OAEP-256"
}
encrypted key 
-зашифровано-
initialization vector 
-зашифровано-
ciphertext 
-зашифровано-
authentication tag 
-зашифровано-
2

Обработать дешифрованный ответ

Полученный ответ (в том числе ошибки) будет представлен в виде компактной сериализации JWS.

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

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

  • •
    Base64URL(Header);
  • •
    Base64URL(Payload);
  • •
    Base64URL(Signature).

Пример JWS

Закодированный Раскодированный
eyJraWQiOiJhbGZhLXRlc3Qtand0IiwidHlwIjoiSldUIiwiYWxnIjoiUlMyNTYifQ.eyJkZWJpdFR1cm5vdmVyIjp7ImFtb3VudCI6MCwiY3VycmVuY3lOYW1lIjoiUlVSIn19.Y1NqCkRjjtJ2GrVsW-a627g6ObfpEaKw-H92QVgVWqL9i7d1SHyaXVghF4ZNZAlrFasKySnKYZf2Ik8zVIlLN7hqeYxoeTdE2OLbiQdvPrD-JnI2Qzh0K32vcImwgGcpq2lt_QKx1f_YmaSRhH9O3xZePVcmFGCqhl_0prQSwcR4g-yuhidvspaF48QlUHcEaZ65Cr8hdyc6g9HPZDy7ipU-zCAZGgK0enxfWn4Osyqch8RRDIsfLG7OJ4wbYwYB22LYO5UaxX8Zy_R2jSnKlNghxQwSqJGxizMFhFhdCrATGTo-ysI-7OtfremD8YNj7z_iYciyYbtAgV0ZodEvMA
header 
{
  "kid": "alfa-test-jwt",
  "typ": "JWT",
  "alg": "RS256"
}
payload 
{
  "debitTurnover": {
    "amount": 0,
    "currencyName": "RUR"
  }
}
verify signature 
RSASHA256(
  base64UrlEncode(header) + "." +
  base64UrlEncode(payload),

)
3

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

Используйте открытый ключ сертификата для проверки подписи.

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

4

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

Пример ответа 
{
  "debitTurnover": {
    "amount": 0,
    "currencyName": "RUR"
  }
}
Подписание TXT ГОСТ-сертификатомШифрование JSON ГОСТ-сертификатом