Приклад запиту до ПП:
| GET https://example.coin/callback.htm? code=2d6f2318cb06cc2c97d948deb9799d608f1d5c97& state=2364fc5d-c6b6-4f99-87a9-11d2baa32484 |
Можливі помилки
Якщо за вищевказаним запитом виникають помилки, то можливі 2 ситуації:
1) ПП не вдалося автентифікувати (зокрема, ПП не зареєстрований на стороні ц.в. BankID НБУ або не співпадає значення певного параметра в запиті) або некоректний запит. У такому випадку опис помилки буде відображено на веб-сторінці ц.в. BankID НБУ;
2) користувача вдалося автентифікувати на стороні АБС банку, проте сталася інша помилка - буде виконано запит із переадресацією користувача на адресу значення redirect_url із можливими значеннями помилок у параметрах запиту, наприклад:
2.1.2. Запит на отримання коду доступу (access_token) методом POST (другий етап)
Після отримання запиту з кодом авторизації ПП повинен ініціювати запит на отримання коду доступу. Структура запиту від ПП до ц.в. BankID НБУ під час якого значення передаються у вигляді стрічки з параметрами на веб-адресу ц. в. BankID НБУ у такому форматі:
У відповідь ц.в. BankID НБУ надає параметри та значення коду доступу в тілі запиту (body) у Json-форматі. Опціонально у відповіді параметра зі значенням refresh_token не обов'язково передається. Використовується, коли термін дії коду доступу (access_token) досить короткий і на ресурсі АБС банку реалізований цей функціонал.
Приклад відповіді ц.в. BankID:
Можливі помилки
У разі виникнення помилок оброблення запиту рекомендуємо орієнтуватися на список кодів стану HTTP. Також можуть передаватися параметри із значеннями помилки, що спричинили відмову, і передаються у тілі відповіді (body) у Json-форматі.
Приклад тіла відповіді з помилкою:
| ( "error": "invalid_grant", "error_description": "Invalid authorizathion code", "code": "2d6f2318cb06cc2c97d948deb9799d608f1d5c97" ) |
2.1.3. (Опціонально). Запит на продовження дії коду доступу (access_token) методом POST
Якщо зі сторони АБС банку отримана відповідь зі значенням параметра refresh_token, то для можливості продовження дії вже отриманого коду доступу (без необхідності виконання всіх попередній викликів) необхідно виконати такий запит:
структура запиту від ПП до ц.в. BankID НБУ - значення передаються у вигляді стрічки з параметрами на вказану веб-адресу центрального вузла BankID НБУ в такому форматі:
У відповідь ц.в. BankID НБУ надає параметри та значення коду доступу в тілі запиту (body) в Json-форматі.
Приклад відповіді ц.в. BankID НБУ:
| HTTP/1.1 200 OK Content-Type: application/json ( "tokenJype": "bearer", "access_token": "db8814c6d97cbad2a02db80el7d4676fab5914c6", "expires_in": 3600 ) |
2.2. Процедура отримання даних користувача
Отримання даних відбувається на підставі коду доступу (access_token), отриманого у ході авторизації (згідно з пунктом 2.1.2.). Код доступу необхідно передавати в заголовку запиту (headers) у вигляді:
Authorization: "Bearer access token"
Сторона ПП у запиті до ц.в. BankID НБУ повинна вказати, який саме набір даних щодо користувача як клієнта банку потрібно передати у відповіді, а також надати свій посилений сертифікат шифрування в форматі base64. Ц.в. BankID НБУ переспрямовує отриманий запит на набір даних від ПП до АБС, у якому було здійснено автентифікацію користувача як клієнта банку.
Посилений сертифікат шифрування передається в атрибуті "cert" у форматі base64. Порядок шифрування анкети визначено в пункті 3.3. цієї специфікації взаємодії.
Перелік необхідних даних указується згідно з допустимими полями у вигляді Json-об'єкту в тілі запиту (body). Якщо якесь із полів буде відсутнє зі сторони АБС, то замовлене поле не повертається або повертається зі значенням "null".
Приклад Json-об'єкта на запит персональних даних:
Тобто для отримання необхідних даних про користувача потрібно передати ті поля структури або підмножину полів, які необхідні (відсутність поля вказує на те, що дані щодо цього поля не потрібні).
2.2.1 Електронна анкета (з переліком та описом допустимих полів)
2.2.2 Запит даних користувача як клієнта банку
Для отримання даних щодо користувача направляється запит від ПП до ц.в. BankID НБУ. Параметри та значення передаються в тілі запиту (body) в Json-форматі.
Приклад запиту щодо даних від ПП:
Відповідь надається у вигляді Json-об'єкта, в якому банк передає через ц.в. BankID НБУ свій посилений сертифікат шифрування та цифровий конверт, що містить зашифровані й підписані персональні дані. Посилений сертифікат шифрування банку міститься в атрибуті "cert" у форматі base64. Цифровий конверт із даними про користувача в підписаному та зашифрованому вигляді разом із зашифрованим ключем шифрування даних містяться в атрибуті "customerCrypto" у форматі base64.
Приклад відповіді:
Розшифрування підписаних персональних даних користувача відбувається згідно з вимогами до форматів криптографічних повідомлень, визначених наказом Адміністрації Державної служби спеціального зв'язку та захисту інформації України від 18.12.2012 № 739 (http://zakon3.rada.gov.ua/laws/show/z0108-13) (далі - Вимоги). Узгодження ключів за замовчуванням здійснюється з використанням статичного механізму. Якщо параметри криптографічного алгоритму статичної ключової пари відправника не еквівалентні параметрам криптографічного алгоритму статичної ключової пари одержувача, повинен здійснюватися перехід до застосування динамічного механізму узгодження ключів. Засоби криптографічного захисту інформації відправника та одержувача мають підтримувати криптографічні алгоритми, визначені цими Вимогами.
АБС банку формує Json-об'єкт із персональними даними користувача у вигляді (приклад):
Після цього вказаний Json-об'єкт підписується електронним цифровим підписом банку й шифрується симетричним ключем сеансу (КШД - ключ шифрування даних за алгоритмом, визначеним у ДСТУ ГОСТ 28147-2009). Підписаний та зашифрований об'єкт формується у вигляді цифрового конверта згідно з Вимогами.
Примітка. Сам ключ шифрування даних шифрується узгодженим ключем (КШК - ключ шифрування ключа, симетричний ключ, який обчислюється за протоколом Діффі-Геллмана на підставі пари ключів - відкритого ключа шифрування ПП, отриманого з посиленого сертифіката ПП, та особистого ключа шифрування АБС банку).
Можливі помилки
У разі виникнення помилок оброблення запиту рекомендуємо орієнтуватися на список кодів стану HTTP. Якщо стан запиту дорівнює 200, то необхідно перевіряти тіло запиту (логічна помилка), в іншому випадку - це технічна помилка. Параметри зі значеннями помилки передаються в тілі запиту (body) у Json-форматі
Приклад технічної помилки:
| ( "error": "invalid_token", "error_description": "Invalid access_token", "access_token": "db8814c6d97cbad2a02db80e17d4676fab5914c6" ) |
Приклад логічної помилки:
| ( "error": "invalid_cert", "error_description": "Sertificate not found at EUSignCP.EUPackHelper.EnvelopData(Byte[] data)", "code": "CL003" ) |
3. Захист інформації в системі BankID НБУ
3.1 Загальні положення
Передавання інформації між абонентами системи BankID НБУ має здійснюватися із забезпеченням конфіденційності та контролю цілісності.
ПП абонентів-надавачів послуг, абоненти-ідентифікатори (банки), центральний вузол системи BankID НБУ забезпечують ідентифікацію й автентифікацію у своїх інформаційно-телекомунікаційних системах із використанням криптографічного протоколу TLS (Transport Layer Security), вимоги до якого наведено нижче.
У системах абонентів-надавачів послуг, абонентів-ідентифікаторів (банків), центрального вузла системи BankID НБУ здійснюється реєстрація подій шляхом ведення журналу аудиту.
Журнал аудиту ПП абонента-надавача послуг повинен містити відомості про факт відправлення електронного запиту на ідентифікацію до центрального вузла системи BankID НБУ, отримання електронного підтвердження ідентифікації від центрального вузла системи BankID НБУ, результат розшифрування електронного підтвердження ідентифікації, результат перевірки ЕЦП, накладеного абонентом-ідентифікатором (банком).
Журнал аудиту абонента-ідентифікатора (банку) повинен містити відомості про факт звернення користувача системи BankID НБУ, результат опрацювання звернення користувача системи BankID НБУ, факт відправлення електронного підтвердження ідентифікації центральному вузлу системи BankID НБУ.
Журнал аудиту центрального вузла системи BankID НБУ повинен містити відомості про факт проходження електронного запиту на ідентифікацію від абонента-надавача послуг через центральний вузол системи BankID НБУ до абонента-ідентифікатора та про факт проходження електронного підтвердження ідентифікації від абонента-ідентифікатора через центральний вузол системи BankID НБУ до абонента-надавача послуг.
Абоненти-надавачі послуг, абоненти-ідентифікатори, адміністратори абонентських вузлів, адміністратор центрального вузла системи BankID НБУ мають право самостійно визначати додаткові події, що фіксуються у відповідних журналах аудиту.
Усі записи в журналах аудиту повинні містити опис події, дату та час події, а також забезпечувати ідентифікацію суб'єкта, який ініціював подію.
Журнали аудиту повинні мати захист від несанкціонованого доступу, модифікації та знищення (руйнування).
Взаємодія центрального вузла системи BankID НБУ з системами абонентів-надавачів послуг та абонентів-ідентифікаторів здійснюється виключно з використанням параметрів та адрес, які узгоджених із адміністратором центрального вузла системи BankID НБУ.
3.2 Вимоги до використання криптографічного протоколу TLS та відповідних сертифікатів відкритих ключів
Портали абонентів-надавачів послуг (ПП), абоненти-ідентифікатори (банки), центральний вузол системи BankID НБУ для встановлення безпечного з'єднання між собою та з користувачами системи BankID НБУ повинні використовувати криптографічний протокол TLS не нижче версії 1.2, а також відповідні особисті ключі та сертифікати відкритих ключів.
У протоколі TLS допускаються різні криптографічні набори.
Криптографічний набір узгоджується між клієнтом та сервером під час встановлення з'єднання. Клієнт передає серверу список підтримуваних криптографічних наборів, а сервер обирає один із них для захисту інформації.
Сервери не повинні застосовувати криптографічні набори, які не використовують шифрування або коли для шифрування використовується алгоритм RC4 (у ролі EncryptionAlg встановлено NULL або RC4).
Для шифрування інформації повинні використовуватися симетричні криптографічні алгоритми з довжиною ключа не менш як 128 біт.
Не рекомендується застосовувати криптографічні набори, які для обміну ключами застосовують статичний RSA. Довжина відкритого ключа RSA повинна бути не меншою ніж 2048 біт. Заборонено застосовувати криптографічні набори, які використовують попередньо узгоджений загальний секретний ключ (PSK).
Для узгодження сеансових ключів використовуються протоколи DHE та ECDHE. Довжина відкритого ключа для протоколу DH повинна бути не меншою ніж 2048 біт. Довжина відкритого ключа для протоколу ECDHE повинна бути не меншою ніж 256 біт.
Рекомендується використовувати такі криптографічні набори:
TLS_DHE_RSA_WITH_AES_128_GCM_SHA256;
TLS_ECDHE_RSA_WITH_AES_128_GCM_SHA256;
TLS_DHE_RSA_WITH_AES_256_GCM_SHA384;
TLS_ECDHE_RSA_WITH_AES_256_GCM_SHA384.
Абоненти-надавачі послуг, абоненти-ідентифікатори, центральний вузол системи BankID НБУ використовують сертифікати відкритих ключів розширеної перевірки (Extended Validation Certificates, далі - EV SSL сертифікат) у форматі X.509 версії 3.
Рекомендується використовувати браузери провідних розробників (таких як Apple, Google Inc., Microsoft Corporation, Mozilla Foundation, Opera Software ASA) та отримувати EV SSL сертифікати від центрів сертифікації ключів (certificate authority/CA), довірених для відповідних браузерів.
EV SSL сертифікат не повинен мати тип Wildcard. У розширенні "Додаткові дані підписувача" ("subjectAlternativeName") EV SSL сертифіката не допускається використання URL, який відрізняється від URL, зазначеного в "реквізиті підписувача" ("commonName") поля "Підписувач" ("subject").
3.3 Вимоги до забезпечення конфіденційності та контролю цілісності електронної анкети
Абонент-ідентифікатор (банк) перед передаванням електронного підтвердження ідентифікації з інформацією про користувача через систему BankID НБУ послідовно виконує такі операції:
накладає на електронне підтвердження ідентифікації свій електронний цифровий підпис відповідно до вимог Закону України "Про електронний цифровий підпис" ;
шифрує підписане електронне підтвердження ідентифікації з використанням посиленого сертифіката шифрування того абонента-надавача послуг, якому передає електронну анкету.
Шифрування/розшифрування електронного підтвердження ідентифікації відбувається згідно з алгоритмами та правилами шифрування даних, визначеними Вимогами до форматів криптографічних повідомлень, затверджених наказом Адміністрації Державної служби спеціального зв'язку та захисту інформації України від 18.12.2012 № 739 (http://zakon3.rada.gov.ua/laws/show/z0108-13). Узгодження ключів шифрування за замовчуванням здійснюється з використанням статичного механізму. Якщо параметри криптографічного алгоритму статичної ключової пари відправника не еквівалентні параметрам криптографічного алгоритму статичної ключової пари одержувача, має здійснюватися перехід до застосування динамічного механізму узгодження ключів.
Абонент-ідентифікатор накладає на електронне підтвердження ідентифікації свій електронний цифровий підпис із використанням формату "ЕЦП із повним набором даних перевірки" (CAdES-X Long відповідно до ДСТУ ETSI TS 101733:2009).
Накладення електронного цифрового підпису на електронне підтвердження ідентифікації здійснюється відповідно до Вимог до формату підписаних даних, затверджених наказом Міністерства юстиції України, Адміністрації Державної служби спеціального зв'язку та захисту інформації України від 20.08.2012 № 1236/5/453 та зареєстрованих у Міністерстві юстиції України 20.08.2012 за № 1401/21713 (зі змінами).
( Додаток 8 в редакції Рішення Національного банку № 740-рш від 05.11.2018 )
( Текст взято з сайту НБУ http://www.bank.gov.ua )