• Посилання скопійовано
Документ підготовлено в системі iplex

Про затвердження Публічної пропозиції Національного банку України на укладення Єдиного договору банківського обслуговування та надання інших послуг Національним банком України

Національний банк України  | Рішення, Форма типового документа, Повідомлення, Перелік, Заява, Пропозиції від 03.01.2017 № 2-рш
Редакції
Реквізити
  • Видавник: Національний банк України
  • Тип: Рішення, Форма типового документа, Повідомлення, Перелік, Заява, Пропозиції
  • Дата: 03.01.2017
  • Номер: 2-рш
  • Статус: Документ діє
  • Посилання скопійовано
Реквізити
  • Видавник: Національний банк України
  • Тип: Рішення, Форма типового документа, Повідомлення, Перелік, Заява, Пропозиції
  • Дата: 03.01.2017
  • Номер: 2-рш
  • Статус: Документ діє
Редакції
Документ підготовлено в системі iplex
Сервіс-провайдер забезпечує перевірку автентичності користувача, генерацію коду авторизації користувача, надання і перевірку коду доступу та подальшу взаємодію з відповідним сервісом АБС банку для отримання електронної анкети з персональними даними користувача (п. 2.2).
Персональні дані користувача від АБС банку передаються до сервіс-провайдера і далі в центральний вузол системи BankID НБУ у зашифрованому вигляді таким чином, щоб сервіс-провайдер не мав змоги ознайомитися зі змістом персональних даних. Вимоги до використання криптографічного протоколу захисту, сертифікатів ключів, забезпечення конфіденційності та контролю цілісності електронної анкети наведені у п. 3 цієї специфікації взаємодії.
2. Технічна архітектура системи
Взаємодія центрального вузла системи BankID НБУ з АБС відбувається на базі протоколу OAuth2.0 згідно зі специфікацією (що розташована за веб-адресою http://tools.ietf.org/html/rfc6749). Рекомендовано використовувати готові рішення з веб-сайту http://oauth.net/2/ - секція "Code and Services", варіанти під усі популярні платформи та мови програмування.
Ідентифікація користувача відбувається засобами АБС відповідного банку чи АБС сервіс-провайдера, який представляє інтереси банку. Дані, що передаються в запиті АБС до ПП, шифруються симетричним ключем сеансу або ключем шифрування даних за алгоритмом, визначеним у ДСТУ ГОСТ 28147-2009. В основі передачі даних лежить SSL-протокол.
Логіка роботи системи BankID НБУ побудована на організації звернень від ПП до АБС конкретного банку через єдиний шлюз, яким є центральний вузол системи BankID НБУ (далі - ц.в. BankID НБУ) та адресному передаванні необхідних даних від АБС банку до ПП у підписаному та зашифрованому вигляді. Усі абонентські вузли (як ПП, так і банків) взаємодіють виключно через ц.в. BankID НБУ.
Для підключення банку до ц.в. BankID НБУ уповноважена особа від банку надає веб-адресу АБС банку, на яку ініціюватимуться запити від ц.в. BankID НБУ до АБС (login_url ) та веб-адреси, на які здійснюватимуться запити на код доступу (token_api_url ) та на персональні дані (data_api_url ) від ц.в. BankID НБУ. Адміністратор ц.в. BankID НБУ видає уповноваженій особі банку унікальні ідентифікатори параметрів з'єднання (client_id, client_secret ). Усі зазначені параметри обов'язкові, мають бути фіксовані і не повинні містити змінних параметрів (зміни в адресах повинні узгоджуватися з адміністратором центрального вузла системи BankID НБУ).
Параметри Опис
client_id Унікальний ідентифікатор ресурсу АБС, виду стрічки 32-шістнадцяткових значень, розділеної на групи дефісами.
Надається адміністратором ц.в. BankID НБУ під час реєстрації, наприклад: 95e4ba81-06ad-4e97-b9d9-0728fbed074f
client_secret Унікальний ідентифікатор секрету ресурсу АБС, виду стрічки 32-шістнадцяткових значень. Надається адміністратором ц.в BankID НБУ під час реєстрації, наприклад: 5d42123a80942fda030c893c951fc08
login_url Веб-адреса АБС банку, на яку буде переадресовано користувача з веб-сторінки ц.в. BankID НБУ. Надається стороною банку під час реєстрації, наприклад: https://id.example.com.ua/oauth2/authorize
Веб-адреса буде доповнена параметрами та значеннями згідно з п. 2.1.1
token_api_url Веб-адреса АБС банку, на яку здійснюватиметься запит для отримання коду доступу (access_token). Надається банком під час реєстрації, наприклад: https://id.example.com.ua/oauth2/v1/bankid/token
data_api_url Веб-адреса АБС банку, на яку здійснюватиметься запит для отримання персональних даних користувача. Надається банком під час реєстрації, наприклад: https://id.example.com.ua/oauth2/v1/bankid/client
Рис. 2. Технологічна схема функціонування системи BankID НБУ
2.1. Процедура авторизації
Авторизація згідно зі стандартом OAuth 2.0 виконується у два етапи:
перший етап - отримання коду авторизації (authorization_code), параметр отриманий у запиті на веб-адресу callback_url, вказану в запиті п. 2.1.1;
другий етап - отримання коду доступу (access_token) на підставі коду авторизації (запит на адресу банку, значення параметра token_api_url, вказану під час реєстрації, п. 2.1.2).
Примітка. Веб-сторінка АБС банку, на якій користувач проходить процедуру автентифікації та погоджує процес передачі персональних даних, повинна бути брендована під конкретний банк, мати контактний телефон гарячої лінії з можливістю переходу користувача на веб-сторінку з контактною інформацією відповідного банку або форму зворотного зв'язку.
Якщо банк делегує функції автентифікації та авторизації сервіс-провайдеру, то описані нижче методи повинні бути реалізовані на стороні сервіс-провайдера.
2.1.1. Перехід на сторінку АБС методом GET (перший етап)
Структура запиту від ц.в. BankID НБУ до АБС, запит формується під час переадресації користувача з банера банку на веб-сторінці ц.в. BankID НБУ у такому форматі:
GET https://example.bank.com/v1/bank/oauth2/authorize?response_type=code& HTTP/1.1
client_id=client_id&
redirect_uri=callback_url&
state=state
Параметр Опис
callback_url Веб-адреса ц.в. BankID НБУ, на яку буде виконано запит із кодом авторизації (authorization_code ) і на яку буде виконано переадресацію користувача.
Адреса фіксована, не повинна містити змінних параметрів
state Ідентифікатор сесії. Генерується на стороні ц.в. BankID НБУ і має бути повернутий у запиті з кодом авторизації на веб-адресу ц.в. BankID НБУ, вказану у значенні callback_url або у випадку помилок. Наприклад: 2baeadd0-c7e6-4ad9-9181-1fd9bbebfaac
Приклад запиту, за якого користувач перейде з веб-сторінки ц.в. BankID НБУ на веб-сторінку АБС банку:
GET https://example.bank.com/v1/bank/oauth2/authorize?response_type=code&
client_id=95e4ba81-06ad-4e97-b9d9-0728fbed074f&
redirect_uri=https://id.bank.gov.ua/v1/bank/oauth2/callback/code&
state =2baeadd0-c7e6-4ad9-9181-1 fd9bbebfaac
Відповідь АБС банку:
HTTP/1.1 200 OK
Перехід на веб-сторінку АБС банку для подальшої ідентифікації користувача в системі банку.
За умови успішної автентифікації користувача в АБС банку від АБС буде виконано запит із кодом авторизації (authorization_code ) і переадресацією користувача.
У разі успішної автентифікації користувача на стороні АБС банку система банку повинна зробити запит із кодом авторизації на адресу параметра redirect_uri. Із даним запитом відбувається переадресація користувача до ц. в. BankID НБУ.
Приклад запиту від АБС банку:
GET https: //id.bank.gov.ua/v 1 /bank/oauth2/callback/code?
code=2d6f2318cb06cc2c97d948deb9799d608fl d5c97&
state=2364fc5d-c6b6-4f99-87a9-lld2baa32484
Можливі помилки
Якщо під час здійснення вказаного запиту виникають помилки, то можливі дві ситуації:
• не вдалося автентифікувати запит (зокрема, ц.в. BankID НБУ не зареєстрований на стороні банку або не збігається значення певного параметра в запиті) або некоректний запит. У такому випадку опис помилки повинен бути відображений на веб-сторінці АБС.
• користувача вдалося автентифікувати на стороні АБС банку, проте сталася інша помилка - буде виконано запит із переадресацією користувача на адресу значення redirect_uri з можливими значеннями помилок у параметрах запиту, наприклад:
GET https://id.bank.gov.ua/v1/bank/oauth2/callback/code?
Content-Type: application/x-www-form-urlencoded
error=access_denied&
error_description=No_rights_for_BankID&
state=2364fc5d-c6b6-4f99-87a9-11d2baa32484
Параметр Опис
error Один із визначених кодів помилки згідно зі специфікацією OAuth2.0 (https://tools.ietf.org/html/rfc6749#section-4.1.2.1).
Зокрема:
invalid_request - у запиті немає обов'язкових значень або недопустимі значення певного параметра;
unauthorized_client - неможливо отримати код авторизації;
access_denied - запит заборонений
error_description Можливий текстовий опис помилки, деталізація для розробників
state Буде вказано значення ідентифікатора сесії
2.1.2. Запит на отримання коду доступу (access_token) методом POST
(другий етап)
Після отримання запиту з кодом авторизації ц.в. BankID ініціює запит на отримання коду доступу. Структура запиту від ц.в. BankID НБУ до АБС, за якого значення передаються у вигляді стрічки з параметрами на веб-адресу, що надана банком під час реєстрації token_api_url (п. 2) у такому форматі:
POST https://example.bank.com/v1/bank/oauth2/token HTTP/1.1
Content-Type: application/x-www-form-urlencoded
grant_type=authorization_code&
client_id=client_id&
client_secret=client_secret&
code=code&
redirect_uri=callback_url
Параметр Опис
grant_type Тип запиту, який повинен мати значення "authorization_code".
(Інакше запит на продовження дії коду доступу (access_token ) (п. 2.1.3), значення буде "refresh_token" )
code Код авторизації (authorization code ), отриманий на попередньому кроці (п. 2.1.1)
callback_url Адреса ц.в. BankID НБУ використовується для переадресації в разі виникнення помилок під час отримання коду доступу (access_token )
У відповідь АБС банку надає параметри та значення коду доступу в тілі запиту (body) у Json-форматі. Опціонально: у відповіді параметр зі значенням refresh_token зазначається, якщо термін дії коду доступу (access_token ) досить короткий і на ресурсі АБС банку реалізований даний функціонал для оновлення запиту.
Приклад відповіді ц.в. BankID:
HTTP/1.1200 OK
Content-Type: application/json
(
"token_type": "bearer",
"access_token": "db8814c6d97cbad2a02db80e17d4676fab5914c6",
"expires_in": 3600,
"refresh_token": "91ee282ccda4e1af6dbd0da4920b206866278f5e"
)
Параметр Опис
token_type Вказується тип запиту, за якого передається код доступу, повинен мати значення "bearer"
access_token Значення коду доступу
expires_in Термін дії коду доступу (значення в секундах)
refresh_token Код оновлення запиту (опціонально, якщо підтримується АБС)
Можливі помилки
У разі виникнення помилок оброблення запиту рекомендуємо орієнтуватися на список кодів стану HTTP. У відповідь АБС надає параметри зі значеннями помилки, що спричинили відмову, і передає у тілі відповіді (body ) у Json-форматі.
Приклад тіла відповіді з помилкою:
( "error": "invalid_grant", "error_description": "Invalid authorizathion code", "code":
"2d6f2318cb06cc2c97d948deb9799d608f1d5c97" )
Параметр Опис
error Один із визначених кодів помилки згідно зі специфікацією OAuth2.0 (https://tools.ietf.org/html/rfc6749#section-5.2).
Наприклад:
invalid_request - у запиті немає обов'язкових значень або неправильно сформовані значення одного або кількох параметрів;
invalid_grant - некоректний код авторизації (authorization_code ) або термін дії коду авторизації вичерпано
error_description Можливий текстовий опис помилки, деталізація для розробників
code Буде вказано значення коду авторизації (authorization_code )
2.1.3. (Опціонально) Запит на продовження дії коду доступу (access_token) методом POST
Якщо зі сторони АБС банку отримана відповідь зі значенням параметра refresh_token, то для можливості продовжити дію вже отриманого коду доступу (без необхідності виконання всіх попередніх викликів) необхідно виконати такий запит.
Структура запиту від ц.в. BankID НБУ до АБС, значення передаються у вигляді стрічки з параметрами на вказану веб-адресу банку (надавалася банком під час реєстрації token_api_url, п. 2) у такому форматі:
POST https://example.bank.com/v1/bank/oauth2/token HTTP/1.1
Content-Type: application/x-www-form-urlencoded
grant_type=refresh_token&
client_id=client_id&
client_secret=client_secret&
refresh_token=refresh_token
Параметр Опис
grant_type Вказується тип запиту, який на даному кроці повинен мати значення "refresh_token"
refresh_token Значення токена (refresh_token ), отриманого на попередньому кроці (п. 2.1.2)
У відповідь АБС банку надає параметри та значення коду доступу в тілі запиту (body ) в Json-форматі.
Приклад відповіді АБС банку:
HTTP/1.1 200 OK
Content-Type: application/json
(
"tokentype": "bearer",
"access_token": "db8814c6d97cbad2a02db80e17d4676fab5914c6",
"expires_in":3600,
)
2.2. Процедура отримання даних користувача
Надання даних відбувається на підставі коду доступу (access_token), отриманого в ході авторизації (згідно з попереднім пунктом). Код доступу передається в заголовку запиту (headers) у вигляді:
Authorization: "Bearer access_token "
Сторона ПП в запиті до ц.в. BankID НБУ повинна вказати, який саме набір даних стосовно користувача як клієнта банку потрібно передати у відповіді, а також надати свій посилений сертифікат шифрування у форматі base64. Ц.в. BankID НБУ переспрямовує отриманий запит на набір даних від ПП до АБС, у якому було здійснено автентифікацію користувача як клієнта банку.
Посилений сертифікат шифрування передається в атрибуті "cert " у форматі base64. Порядок шифрування анкети визначено в пункті 3.3 цієї специфікації.
Перелік необхідних даних указується згідно з допустимими полями у вигляді Json-об'єкту в тілі запиту (body ). Якщо якесь із полів буде відсутнє зі сторони АБС, то замовлене поле не повертається або повертається зі значенням "null".
Приклад Json-об'єкта на запит персональних даних:
(
"type": "physical",
"cert": "dEBIGx1pdL6dt1ngaOEfPvt/ik9eUpDuz90rm/Vk23v+FtiKJEvGnuea9FGjvBMGlFZS4zhg2IYIHGOhlBVYrZcez6udotjZlCLGZ7zwPuFoOXypKDQj5qpR7w0rFFZNjcPH3JW2IzEUv",
"fields": ["firstName", "middleName", "lastName", "phone", "inn", "birthDay",
"flagPEPs", "flagPersonTerror", "flagRestriction", "flagTopLevelRisk"],
"scans": [
( "type": "passport", "fields": ["scanFile", "dateCreate", "extension"] ),
( "type": "zpassport", "fields": ["scanFile", "dateCreate", "extension"] )
],
"addresses": [
( "type": "factural", "fields": ["country", "state", "area", "city", "street", "houseNo", "flatNo"] ),
( "type": "birth", "fields": ["country", "state", "area", "city"] ),
( "type": "juridical", "fields": ["country", "state", "area", "city", "street", "houseNo", "flatNo"] ),
],
"documents": [
( "type": "passport", "fields": [
"series", "number", "issue", "dateIssue", "dateExpiration", "issueCountryIso2"
] ),
( "type": "zpassport", "fields": [
"series", "number", "issue", "dateIssue", "dateExpiration", "issueCountryIso2"
] )
]
)
Тобто для отримання необхідних даних про користувача потрібно передати всі поля структури або підмножину полів, які необхідні (відсутність поля вказує на те, що дані щодо цього поля не потрібні).
2.2.1. Електронна анкета (з переліком та описом допустимих полів)
Блок Поле Опис
cert cert Посилений сертифікат шифрування ПП (у форматі base64), обов'язково для заповнення
type physical Значення ідентифікації фізичної особи
fields lastName Прізвище
firstName Ім'я
middleName По батькові
phone Номер телефону (у форматі 380XXXXXXXXX)
inn Ідентифікаційний номер (у випадку відмови від нього з релігійних причин може бути заповнене однаковими цифрами, наприклад 00000000000)
clId Ідентифікатор клієнта в банку
clIdText Статичний текст з інформацією про надані дані банком щодо користувача, дата і час надання: "Інформація надана засобами системи BankID НБУ dd.MM.yyyy HH.mm"
birthDay Дата народження (у форматі dd.MM.yyyy)
sex Стать (M - чоловік, F - жінка)
email Електронна адреса
socStatus Соціальний статус (наприклад, студент, пенсіонер, безробітний, працюючий, нерегулярна зайнятість)
FlagPEPs Ознака, чи визначена фізична особа банком-повіреним такою, що належить до категорії PEPs [(публічні особи, близькі, пов'язані) (Можливі значення: 1 - визначено, 0 або не заповнено - не визначено)]
FlagPersonTerror Ознака, чи визначена фізична особа банком-повіреним такою, що включена до переліку осіб, пов'язаних зі здійсненням терористичної діяльності або щодо яких застосовано міжнародні санкції (можливі значення: 1 - визначено, 0 або не заповнено - не визначено)
FlagRestriction Ознака, чи визначена фізична особа банком-повіреним такою, що включена до переліку осіб, щодо яких застосовані персональні, спеціальні економічні та інші обмежувальні заходи (санкції), санкції РНБОУ (можливі значення: 1 - визначено, 0 або не заповнено - не визначено)
FlagTopLevelRisk Ознака, чи присвоєний клієнту банком- повіреним (неприйнятно) високий рівень ризику ПФК/ФТ (можливі значення: 1 - присвоєно, 0 або не заповнено - не присвоєно)
addresses type Тип адреси, допустимі значення:
factual - фактична адреса проживання;
juridical - адреса реєстрації (штамп у паспорті)
country Країна (двозначний літерний код країни).
Наприклад: UA
state Область
area Район
city Місто
street Вулиця
houseNo Номер будинку
flatNo Номер квартири
documents type Тип документа, допустимі значення:
passport - паспорт;
zpassport - закордонний паспорт;
idpassport - id-картка;
ident - посвідчення особи
typeName Назва документа
series Серія документа (відсутня в idpassport )
number Номер документа
issue Ким виданий документ
dateIssue Коли виданий (у форматі dd.MM.yyyy)
dateExpiration Термін дії (у форматі dd.MM.yyyy)
issueCountryIso2 Країна видачі документа (двозначний літерний код країни). Наприклад: UA
scans type Копія документів, допустимі значення:
passport - паспорт;
zpassport - закордонний паспорт;
inn - сканована копія ідентифікаційного податкового номера; personalPhoto - фото особи
scanFile Файл сканованої копії (у форматі base64)
dateCreate Дата створення документа (у форматі dd.MM.yyyy)
extension Розширення файла
2.2.2. Запит даних користувача як клієнта банку
Для отримання даних щодо користувача направляється запит від ц.в. BankID НБУ до АБС за веб-адресою, наданою банком під час реєстрації (data_api_url) (п. 2). Параметри та значення передаються в тілі запиту (body) в Json-форматі.
Приклад запиту щодо даних до АБС банку:
POST https://example.bank.com/v1/bank/resource/client HTTP/1.1
Authorization: Bearer access_token
Content-Type: application/json
(
"type": "physical",
"cert": "dEBIGxlpdL6dtlngaOEfPvt/ik9eUpDuz90rm/Vk23v+FtiKJEvGnuea9FGjvBMGlFZS4zhg2IYIHGOhlBVYrZcez6udotjZlCLGZ7zwPuFoOXypKDQj5qpR7w0rFFZNjcPH3JW2IzEUv",
"fields": [
"firstName", "middleName", "lastName", "phone", "inn", "clId", "clIdText", "birthDay"],
scans": [( "type": "passport", "fields": ["scanFile", "dateCreate", "extension"] )],
"addresses": [
( "type": "factural", "fields": ["country", "state", "area", "city", "street", "houseNo", "flatNo"] )],
"documents": [
( "type": "passport", "fields": [
"series", "number", "issue", "dateIssue", "dateExpiration", "issueCountryIso2"] )
]
)
Параметр Опис
access_token Код доступу, отриманий у відповіді від АБС
Відповідь надається у вигляді Json-об'єкта, в якому банк надає свій посилений сертифікат шифрування та цифровий конверт, що містить підписані та зашифровані персональні дані. Посилений сертифікат шифрування банку міститься в атрибуті "cert" у форматі base64. Цифровий конверт із даними про користувача у підписаному та зашифрованому вигляді разом із зашифрованим ключем шифрування даних містяться в атрибуті "customerCrypto" у форматі base64.
Приклад відповіді:
НТТР/1.1200 OK
Content-Type: application/json
(
"state": "ok",
"cert": "dEBIGx1pdL6dt1ngaOEfPvt/ik9eUpDuz90rm/Vk23v+FtiKJEvGnuea9FGjvBMGlFZS4zhg2IYIHGOhlBVYrZcez6udotjZlCLGZ7zwPuFoOXypKDQj5qpR 7w0rFFZNjcPH3JW2IzEUv",
"customerCrypto":
"dEBIGx1pdL6dt1ngaOEfPvt/ik9eUpDuz90rm/Vk23v+FtiKJEvGnuea9FGjvBMGlFZS4zhg2IYIHGOhlBVYrZcez6udotjZlCLGZ7zwPuFo0XypKDQj5qpR7w0rFFZNjcPH3JW2IzEUv/4bXQWqYCccma03b31bva+YJ/Txox1CMfyV4jJ5DCeCMOjEWxwctEc7mXNzPfcbKMoqr048uvW9HTiPkjsLIU5jgTKJVdgoanZI4712dmQev5UzMKqNYvOwfJ+hU872kCSD1wfgVaJU0qP6yURcK80ys2K5OvUpa9uIHwmL7KmnxMDhB4hLr5CQPl1XZ09PvnNykgS/4cQ"
)
Шифрування підписаних персональних даних відбувається відповідно до вимог до форматів криптографічних повідомлень, визначених наказом Адміністрації Державної служби спеціального зв'язку та захисту інформації України від 18.12.2012 № 739 (http://zakon3.rada.gov.ua/laws/show/z0108-13) (далі - Вимоги). Узгодження ключів за замовчуванням здійснюється з використанням статичного механізму. Якщо параметри криптографічного алгоритму статичної ключової пари відправника не еквівалентні параметрам криптографічного алгоритму статичної ключової пари одержувача, повинен здійснюватися перехід до застосування динамічного механізму узгодження ключів. Засоби криптографічного захисту інформації відправника та одержувача повинні підтримувати криптографічні алгоритми, визначені цими Вимогами.
АБС банку формує Json-об'єкт із персональними даними користувача у вигляді (приклад):
( "type": "physical",
"inn": "112233445566",
"sex": "M",
"email": "geraschenko@gmail.com",
"birthDay": "20.01.1953",
"firstName": "ПЕТРО",
"lastName": "ГЕРАЩЕНКО",
"middleName": "ІВАНОВИЧ",
"phone": "380961234511",
"clId": "6299E05EC5D568733C14CCEF9C975DD3",
"clIdText": " Інформація надана засобами BankID НБУ 25.12.2017 19:40",
"socStatus": "пенсіонер",
"flagPEPs": "0",
"flagPersonTerror": "1",
"flagRestriction": "0",
"flagTopLevelRisk": "1",
"addresses": [(
"type": "factual",
"country": "UA",
"state": "ВОЛИНСЬКА",
"city": "Ківерці",
"street": "Незалежності",
"houseNo": "62",
"flatNo": "12"
),],
"documents": [(
"type": "passport",
"series": "AA",
"number": "222333",
"issue": "Ківерцівським РВ УМВС",
"dateIssue": "15.03.99",
"issueCountryIso2": "UA"
)],
"scans": [(
"type": "passport",
"scanFile":
"H4sIAEAOS8dVhczZYuHtxdQiBA4wRraNwdgru7NO7uFpwEd3c LwT...",
"dateCreate": "09.04.2015",
"extension": "zip"
)] )
Після цього вказаний Json-об'єкт підписується електронним цифровим підписом банку і шифрується симетричним ключем сеансу (КШД - ключ шифрування даних за алгоритмом, визначеним у ДСТУ ГОСТ 28147-2009). Підписаний та зашифрований об'єкт формується у вигляді цифрового конверта згідно з Вимогами.
Примітка. Сам ключ шифрування даних шифрується узгодженим ключем (КШК - ключ шифрування ключа, симетричний ключ, який обчислюється за протоколом Діффі-Геллмана на підставі пари ключів - відкритого ключа шифрування ПП, отриманого з посиленого сертифіката ПП, та особистого ключа шифрування АБС банку).
Можливі помилки
У разі виникнення помилок оброблення запиту рекомендуємо орієнтуватися на список кодів стану HTTP. Якщо стан запиту дорівнює 200, то необхідно перевіряти тіло запиту (логічна помилка), в іншому випадку - це технічна помилка. Параметри зі значеннями помилки передаються в тілі запиту (body) у Json-форматі.
Приклад технічної помилки:
( "error": "invalid_token", "error_description": "Invalid access_token",
"access_token": "db8814c6d97cbad2a02db80el7d4676fab5914c6" )
Приклад логічної помилки:
( "error": "invalid_cert", "error_description": "Sertificate not found at EUSignCP.EUPackHelper.EnvelopData(Byte[] data)", "code": "CL003" )
Параметр Опис
error Приклади технічних помилок:
invalid_request - у запиті немає обов'язкових або неправильно сформованих значень;
invalid_token - некоректний код доступу (access_token ) або термін дії коду доступу вичерпано.
Приклади логічних помилок:
invalid_cert - проблеми під час оброблення посиленого сертифіката, зокрема некоректний/недійсний сертифікат або проблеми з підписом;
invalid_data - поля в запиті щодо користувача некоректні
error_description Можливий текстовий опис помилки, деталізація для розробників
code Буде вказано значення коду, за яким виникла помилка
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 (зі змінами).
( Додаток 7 в редакції Рішення Національного банку № 740-рш від 05.11.2018 )
Додаток 8
до Публічної пропозиції
Національного банку України
на укладення Єдиного договору
банківського обслуговування
та надання інших послуг
Національним банком України
Специфікація взаємодії з системою BankID Національного банку України (взаємодія системи BankID НБУ з порталом послуг)
Аркуш контролю версій
Версія Дата Опис
1.0 13.07.2015 Перша версія для загального обговорення
1.1 27.07.2015 Виправлення зауважень, отриманих від НБУ
2.0 30.11.2015 Зміна версії
3.0 04.12.2015 Доповнення протоколу взаємодії системи BankID НБУ - Банк: можливість взаємодії через сервіс-провайдера;
передача даних анкети користувача в зашифрованому вигляді
3.1 10.03.2016 Виправлення URL (додавання /bank/)
3.2 13.10.2016 Додавання розділу щодо захисту інформації
3.3 31.10.2016 Унесені правки для узгодження тексту розділів із змістом розділу щодо захисту інформації
4 17.10.2018 Унесено правки та роз'яснення щодо порядку запитів у процесі взаємодії, доповнено види можливих помилок та роз'яснення щодо загального підходу шифрування/розшифрування даних.
Доповнено перелік допустимих полів для запиту персональних даних.
Унесено виправлення для узгодження з новою редакцією Положення про систему BankID
Національного банку України.
Зміна версії
Глосарій
Термін, скорочення Визначення
1 АБС Автоматизована банківська система - автоматизована система банку - комплекс програмно-технічних засобів, спрямований на автоматизацію банківської діяльності. Забезпечує інтеграцію різних підсистем, кожна з яких спрямована на виконання тієї чи іншої сфери діяльності банку. У даному документі використовуються такі приклади підсистем АБС: ІБ (інтернет-банкінг).
2 Авторизація Процес надання фізичній особі прав на виконання певних дій або доступу до ресурсів, а також процес перевірки (підтвердження) прав під час спроби виконання цих дій
3 Автентифікація Процес перевірки достовірності. В системі BankID НБУ це електронна процедура, що дає змогу підтвердити електронну дистанційну ідентифікацію фізичної особи.
4 ІБ Інтернет-банкінг - технологія дистанційного банківського обслуговування, доступна користувачу за допомогою звичайного браузера з будь-якого комп'ютера, який має вихід в Інтернет.
5 Ідентифікація Ідентифікація - дистанційна ідентифікація - процес розпізнавання фізичної особи абонентами - надавачами послуг шляхом підтвердження автентифікації Користувача системи BankID НБУ абонентом-ідентифікатором.
6 Посилений сертифікат шифрування Сертифікат відкритого ключа, виданий акредитованим центром сертифікації ключів, який використовується в процесі обчислення узгодженого ключа шифрування ключів згідно з Вимогами до форматів криптографічних повідомлень
(затверджені наказом Адміністрації Державної служби спеціального зв'язку та захисту інформації України від 18.12.2012 № 739).
7 ПП Портал послуг - портал (web-сайт, web-портал) абонента - надавача послуг - суб'єкта надання адміністративних послуг, державного або недержавного органу, банку або небанківської установи, на якому ініціюється електронний запит на ідентифікацію користувачів із використанням системи BankID НБУ.
8 Система дистанційного обслуговування Система надання банківських послуг користувачу без його безпосереднього звернення до відділення банку. Перед отриманням послуг користувач проходить попередню ідентифікацію та автентифікацію в системі за встановленою банком технологією.
9 Центральний вузол системи BankID НБУ Комплекс програмно-технічних засобів, відносно якого побудована взаємодія в системі BankID НБУ між ПП та АБС на базі протоколу OAuth2.0. Центральний вузол розміщено на ресурсах Національного банку України.
10 BankID НБУ Комплекс програмно-технічних засобів та організаційно-технологічних заходів для забезпечення дистанційної ідентифікації користувачів під час інформаційної взаємодії між абонентами (ПП та АБС) в електронній формі з використанням банківських систем дистанційного обслуговування.
11 OAuth Відкритий протокол авторизації, який дає змогу третій стороні отримати обмежений доступ до захищених ресурсів користувача без необхідності передавати їй (третій стороні) логін та пароль (протокол розташований за веб-адресою http://oauth.net). У системі BankID НБУ використовується протокол версії 2.0.
1. Загальна частина
1.1. Призначення документа
Опис функціональних вимог та процесу взаємодії Порталу послуг (далі - ПП) із центральним вузлом системи BankID НБУ.
1.2. Цілі створення сервісу
Забезпечення на ПП надійної та зручної ідентифікації користувача через систему BankID НБУ за участю банка (АБС), система якого передбачає ідентифікацію користувача як клієнта банку.
1.3. Концепція функціонування системи
Функціонально система складається з трьох основних блоків:
1. ПП (веб-портал послуг), на якому розміщені форми надання послуг у електронному вигляді (реєстрація/авторизація, замовлення довідок, унесення до реєстрів, надання банківських, небанківських та інших послуг). Під час входу на портал або замовлення послуги користувачу доступна можливість авторизації або ідентифікації за допомогою системи BankID НБУ у вигляді банера або кнопки.
Після натискання кнопки або банера "авторизація/вхід/ідентифікація за допомогою системи BankID НБУ" користувач із веб-сторінки ПП переадресовується на веб-сторінку вибору банку на центральному вузлі системи BankID НБУ, обирає банк, клієнтом якого він є, і спрямовується на веб-сторінку АБС відповідного банку для проведення процедури ідентифікації користувача.
У результаті успішного проходження процедури ідентифікації зі сторони АБС формується електронна анкета з персональними даними користувача (п. 2.2.), після чого користувач автоматично переадресовується назад на веб-сторінку ПП. Одночасно ПП відповідно до порядку отримання даних отримує від АБС через систему BankID НБУ підписану та зашифровану банком анкету з даними користувача.
2. Центральний вузол системи BankID НБУ, на якому розміщена веб-сторінка вибору банку та програмні процедури запиту/передачі даних між АБС та ПП на базі протоколу OAuth2.0.
Після вибору користувачем банку на веб-сторінці центрального вузла системи BankID НБУ користувач переадресовується на веб-сторінку системи дистанційного обслуговування відповідного банку, на якій користувач як клієнт банку проходить стандартну процедуру ідентифікації та автентифікації (наприклад, уводить логін та пароль доступу до ІБ).
У результаті успішного проходження процедури ідентифікації та автентифікації користувача між АБС банку, центральним вузлом системи BankID НБУ та ПП відбувається автоматична взаємодія отримання/передачі коду авторизації (authorization_code ), коду доступу (access_token ) та персональних даних.
3. Банк (АБС: веб-портал інтернет-банкінгу або іншого сервісу банку), на веб-сторінці якого, має бути реалізована форма ідентифікації користувача, програмні процедури автоматичного формування коду авторизації (authorization_code ), коду доступу (access_token ) та електронної анкети (п. 2.2.), накладення на неї електронного цифрового підпису банку, шифрування даних анкети і переспрямування цієї анкети до ПП.
Користувач, перейшовши на веб-сторінку АБС, має можливість ідентифікуватися як клієнт обраного банку, наприклад, за допомогою номера картки банку або з використанням логіна та пароля, отриманих від банку. У разі успішної автентифікації користувач автоматично переспрямовується на сторінку ПП для продовження отримання послуги. Одночасно АБС банку повинна здійснити такі дії: