Імпорт приватного ключа: де ламається гаманець
Імпорт приватного ключа — операція, яка виглядає тривіальною на демо і розвалюється на реальних пристроях.
Користувач вставляє рядок з бекапу, застосунок показує «гаманець відновлено», а баланс порожній: адресу виведено за іншим шляхом деривації, і кошти лежать на гілці, яку інтерфейс не показує.
Це не косметичний дефект — це втрата доступу, і розбиратися в ній приходить людина, у якої на рахунку вже є активи.
Перший клас збоїв — формати ключів. Мнемоніка, WIF, hex без префікса, ключ з контрольною сумою і без неї — усе це різні вхідні дані, і парсер, написаний під один варіант, мовчки приймає решту або падає з незрозумілою помилкою імпорту.
Гірше, коли рядок проходить валідацію, але інтерпретується як ключ іншого типу: гаманець створюється, адреса генерується, доступу до попередніх коштів немає.
Другий клас — обрив запису в захищене сховище. Імпорт — це не одна операція, а послідовність: розшифрувати, перевірити, записати в keychain, оновити стан.
Якщо застосунок згорнули або система вивантажила процес між кроками, залишається половинчастий стан: запис є, а зв'язок з акаунтом не створено. При наступному запуску користувач бачить порожній список і повторює імпорт, плодячи дублікати.
Третій клас — деривація. Один і той самий ключ дає різні адреси залежно від обраної схеми та індексу. Якщо застосунок не дає вибрати схему явно і не показує, яка адреса вийде до підтвердження, користувач дізнається про розходження лише за нульовим балансом. Розбираємо, як це закривається на рівні архітектури, а не латками в інтерфейсі.
Що дає коректний імпорт ключа
Коректний імпорт — це не «поле введення і кнопка». Це розбір формату (WIF, JSON-keystore, BIP39-мнемоніка, raw hex), перевірка контрольної суми, виведення адреси та звірка з очікуваною.
Якщо хоч один крок пропущено, користувач отримує «успішний імпорт» на неправильний ключ — і дізнається про це, коли кошти вже не видно на балансі.
Метрика, за якою ми судимо про якість: частка успішних імпортів з першої спроби. На сирому парсері вона тримається на рівні 70–80% — решта це одруки, зайві пробіли, ключі з іншого формату.
Коли валідація контрольної суми та нормалізація введення вбудовані в потік, частка сягає 95%+. Різниця — це люди, які не пішли в підтримку і не покинули гаманець.
Час відновлення доступу — друга метрика. Якщо імпорт вимагає ручного введення адреси та мережі, користувач витрачає хвилини і помиляється у виборі мережі. Коли застосунок сам визначає мережу за форматом ключа і показує адресу до підтвердження, відновлення вкладається в секунди.
Це напряму впливає на утримання: людина, яка втратила доступ до гаманця, повертається тільки якщо повернула його швидко.
Клас відмов, який закривається коректним імпортом, — «ключ прийнято, але не той». Він небезпечніший за явну помилку: користувач упевнений, що все гаразд, а активи йдуть на адресу, до якої в нього немає доступу.
Перевірка цілісності ключа та звірка виведеної адреси з вихідною прибирають цей клас повністю — імпорт або проходить із підтвердженою адресою, або чесно повідомляє, що ключ не підходить.
Сумісність форматів — третя метрика. Підтримка WIF, JSON-keystore і мнемоніки з автоматичним визначенням формату знімає питання «а мій ключ підійде?». Користувач вставляє рядок, застосунок сам розуміє, що це, і пропонує правильний шлях. Це знижує частку звернень у підтримку і робить імпорт передбачуваним для будь-якого джерела ключа.
Формати ключів і способи їх приймання
Імпорт приватного ключа — це завжди вибір між зручністю введення та контролем над тим, де ключ опиниться після імпорту. Нижче — чотири реальні варіанти, між якими обирають на старті, та їхні інженерні обмеження.
| Варіант | Коли підходить | Обмеження |
|---|---|---|
| Мнемонічна фраза | Відновлення гаманця на новому пристрої, перенесення між застосунками | Потребує перевірки контрольної суми та нормалізації пробілів; чутлива до розкладки й автозаміни; на екрані залишається в буфері обміну |
| Hex-рядок | Імпорт одиночного ключа, службові та тестові сценарії | Немає контрольної суми — друкарська помилка дає валідний, але чужий ключ; довжину й алфавіт потрібно валідувати вручну |
| Файл-сховище | Масове перенесення, вивантаження з іншого гаманця | Форматів багато, частина шифрується паролем; потрібен розбір структури та явна відмова на невідомій версії |
| Апаратний носій | Ключі, які не повинні залишати пристрій | Ключ не витягується — імпортується лише публічна частина; потрібен канал зв'язку з носієм |
Мнемонічна фраза та hex-рядок проходять через поле введення, а отже — через буфер обміну й логи. Ми гасимо це на рівні застосунку: заборона скриншотів на екрані введення, очищення буфера після вставлення, вимкнення автокорекції та підказок клавіатури.
Для файл-сховища додаємо перевірку схеми до запису в захищене сховище пристрою, щоб пошкоджений файл не осів у постійній пам'яті.
Апаратний носій змінює саму модель: приватний ключ не потрапляє в застосунок узагалі, підпис виконується на боці пристрою. Це знімає клас ризиків, пов'язаних із зберіганням, але додає залежність від протоколу обміну та поведінки конкретної моделі.
Обмеження формату визначають, що ми взагалі можемо перевірити до імпорту: контрольну суму, довжину, алфавіт, версію схеми. Усе, що не проходить валідацію, відсікається до запису — інакше гаманець прийме ключ, яким не можна підписати жодну транзакцію.
Як ми вбудовуємо імпорт ключа в застосунок
Імпорт приватного ключа — операція, де одна помилка обнуляє всю модель безпеки гаманця. Тому ми ведемо її як окремий інженерний проєкт із фіксованими етапами, а не як «додати екран із полем введення». Нижче — як влаштований процес від аудиту до передачі рішення вашій команді.
-
Аудит поточної схеми зберігання. Розбираємо, де зараз лежать секрети: у зв'язці ключів операційної системи, у захищеному модулі пристрою або у звичайних файлах і налаштуваннях.
Дивимося, хто має доступ до цих даних, що потрапляє в резервні копії та логи, як влаштоване шифрування при зберіганні. На виході — карта потоків секрету та список місць, де ключ може витекти.
-
Проєктування потоку імпорту. Визначаємо формати введення — мнемонічна фраза, шістнадцятковий рядок, файл сховища — та правила їх валідації. Проєктуємо, як ключ потрапляє в застосунок, де розшифровується і в який момент знищується проміжна копія.
Окремо опрацьовуємо поведінку при помилці: невірна контрольна сума, чужий формат, перерване введення.
-
Налаштування захищеного сховища. Ключ розміщуємо лише в апаратно ізольованому сховищі пристрою, доступ до нього закриваємо біометрією або системним кодом-паролем. Виключаємо потрапляння секрету в знімки екрана, буфер обміну, системні журнали та резервні копії. Приватний ключ не залишає захищений контур навіть у момент підпису транзакції.
-
Перевірка на тестових наборах. Прогоняємо імпорт на підготовлених наборах: коректні ключі різних форматів, пошкоджені дані, граничні випадки, спроби доступу без автентифікації. Перевіряємо відновлення після збою та коректність адрес, які застосунок виводить після імпорту.
-
Передача рішення. Віддаємо вашій команді конфігурацію сховища, схеми потоків, політики обробки секретів і документацію із супроводу. Проводимо розбір коду з розробниками, щоб підтримка імпорту залишалася всередині команди без нашої постійної підтримки.
Кожен етап закінчується перевірюваним артефактом — схемою, конфігурацією або звітом про тести. Опишіть вашу задачу: повернемося з оцінкою термінів і планом робіт за етапами.
Політики доступу та захист ключа на пристрої
Ключ, що потрапив на пристрій, далі живе за правилами, які ми описуємо до першого рядка коду.
Політики доступу задають, хто і за яких умов може ініціювати операцію: підтвердження біометрією або системним кодом, обмеження за часом сесії, заборона на вивантаження матеріалу за межі захищеного контуру.
Конфігурація сховища визначає, де лежить ключ — в апаратному модулі пристрою або в ізольованій області з шифруванням, — і що відбувається при спробі отримати до нього доступ ззовні застосунку.
Окремий шар — захист ключа в момент імпорту: матеріал не повинен опинитися в логах, у тимчасових файлах або в буфері обміну.
Ми проєктуємо потік так, щоб ключ розпаковувався лише в пам'яті та затирався одразу після запису в сховище, а всі проміжні стани були недоступні іншим процесам на пристрої.
На виході замовник отримує комплект, за яким систему можна експлуатувати та передавати між командами:
- конфігурації сховища з описом рівнів захисту та умов їх спрацювання;
- схеми потоків імпорту та підпису — від введення до запису й підтвердження;
- політики доступу: ролі, тригери підтвердження, строк життя сесії;
- регламент відновлення — що робити при втраті пристрою, зміні носія, відкаті;
- матрицю відмов: які сценарії блокуються, які потребують ручного підтвердження;
- документацію для служби підтримки з розбором типових звернень;
- інструкції для аудиту — які події логуються і в якому вигляді зберігаються.
Такий набір знімає головний ризик: коли ключ уже на руках у користувача, а команда не розуміє, за якими правилами він захищений і що робити в нештатній ситуації. Опишіть вашу задачу — повернемося з оцінкою та планом по кожному шару.
Кейс: імпорт ключа без втрати коштів
До нас звернувся замовник із класичним болем: користувачі скаржилися, що після перевстановлення застосунку гаманець не бачив кошти, хоча фразу відновлення було збережено.
Розбір показав, що справа не в блокчейні, а в самому імпорті — різні формати ключів, невідповідність шляхів деривації та відсутність зрозумілої валідації на вході.
З десяти спроб імпорту успішно завершувалися приблизно шість, решта зависали в невизначеному стані: баланс нульовий, транзакції не проходять, користувач не розуміє, що робити далі.
Що було до
Кожен невдалий імпорт перетворювався на звернення до підтримки: людина надсилала скриншоти, ми просили логи, з'ясовували формат ключа, вручну підказували шлях деривації.
На розбір одного випадку йшло в середньому 40 хвилин, а частина користувачів встигала видалити застосунок і втратити доступ до коштів назавжди. Частка успішних імпортів трималася на рівні 62% — при тому, що сам гаманець працював коректно.
Що змінили
Наші інженери переписали сценарій імпорту: додали автоматичне визначення формату ключа, перевірку контрольної суми та явний вибір мережі з попереднім переглядом адреси до підтвердження.
Якщо ключ не підходив під жоден підтримуваний формат, користувач отримував зрозумілу помилку з підказкою, а не порожній екран. Окремо закрили сценарій відновлення після збою — стан імпорту зберігається, і процес можна продовжити з того самого кроку.
Що стало
Частка успішних імпортів зросла з 62% до 99,4%. Час відновлення доступу скоротився з 40 хвилин до 2 хвилин — тепер це кілька екранів із перевіркою адреси.
Звернення до підтримки на тему імпорту впали у 8 разів: типові випадки закриваються підказками прямо в інтерфейсі, а інженерам залишаються тільки справді нестандартні ситуації.
Рішення побудовано на Trust Wallet Core — перевіреній бібліотеці для роботи з ключами на мобільних платформах.
Чим відрізняється імпорт ключа від відновлення за фразою?
Імпорт приватного ключа та відновлення за фразою вирішують одне завдання — повернути користувачеві доступ до коштів на новому пристрої, але йдуть до нього з різних боків.
Під час імпорту ви переносите вже наявний ключ: застосунок приймає його як є, перевіряє формат і контрольну суму, кладе в захищене сховище та підписує ним транзакції.
Під час відновлення за фразою ключ не переноситься — він заново виводиться з мнемоніки за стандартним алгоритмом, і на виході виходить та сама адреса, бо детермінована генерація дає той самий результат на будь-якому пристрої.
Звідси перша різниця в ризиках. Імпортований ключ — це готовий секрет: якщо він утік із буфера обміну, скриншота чи листування, кошти йдуть безповоротно, відкату немає.
Мнемоніка теж секрет, але її зазвичай зберігають офлайн на папері або металі, і вона не проходить через месенджери так часто, як рядки ключів.
Зате у відновлення своя ціна помилки: одна переплутана позиція слова або невірна контрольна сума — і ви отримаєте валідну, але чужу порожню адресу, куди нічого не прийде.
Друга різниця — у перевірках, які ми закладаємо. Для імпорту ключа критично підтвердити, що формат і префікс мережі збігаються, інакше ключ від однієї мережі мовчки створить адресу в іншій.
Для фрази ми перевіряємо кожне слово за словником, порядок і контрольну суму, а після виведення ключа звіряємо отриману адресу з очікуваною — це ловить одруки до того, як користувач відправить кошти. В обох сценаріях ключ не покидає захищений контур пристрою, а після використання буфери очищаються.
Різниця підходів впливає і на підтримку: імпорт вимагає явного попередження про необоротність і підтвердження, що користувач розуміє наслідки, а відновлення — підказок щодо введення та захисту від підміни слів.
Ми розбираємо обидва шляхи окремо, бо змішувати їхні перевірки — прямий спосіб втратити кошти на рівному місці.
Часті технічні сумніви
Імпорт приватного ключа — операція, де ціна помилки максимальна: невірний формат, небезпечне зберігання або збій при читанні з апаратного носія обертаються втратою коштів, а не повідомленням про помилку.
Нижче — технічні сумніви, які найчастіше піднімають замовники на етапі проєктування, і те, як ми їх закриваємо в архітектурі.
Які формати ключів застосунок має приймати?
Сумісність визначається не «популярністю» формату, а тим, які гаманці та носії вже є в користувача. Ми підтримуємо імпорт із поширених текстових і QR-представлень, включно з форматами з мнемонічною фразою та без неї, з перевіркою контрольної суми до запису в сховище. Непідтримуваний формат відсікається на вході з зрозумілим повідомленням, а не «тихою» помилкою.
Як ключ зберігається на пристрої?
Приватний ключ не потрапляє у звичайне сховище застосунку і не пишеться в логи. Він розміщується в захищеній області операційної системи — апаратно підтримуване сховище ключів, доступне лише після біометричної автентифікації.
Це унеможливлює вилучення ключа під час резервного копіювання, налагодження або компрометації самого застосунку.
Чи працює імпорт з апаратними носіями?
Так, для сценаріїв з підвищеними вимогами до безпеки ми реалізуємо роботу з апаратними гаманцями: ключ не залишає пристрій, а застосунок отримує лише підписані транзакції. Це знімає необхідність зберігати ключ на телефоні та переносить перевірку на окремий носій.
Що відбувається при помилці імпорту?
Обробка помилок проєктується як частина користувацького шляху: розрізняються невірний формат, пошкоджена контрольна сума, відмова доступу до захищеного сховища та переривання операції.
Кожен сценарій дає окреме повідомлення і не залишає частково записаних даних — імпорт атомарний, при збої стан відкочується.
Якщо у вас є власні вимоги до сумісності або носіїв — опишіть задачу, і ми повернемося з оцінкою та планом реалізації.
Обговоримо ваше завдання імпорту ключа
Щоб повернутися з оцінкою та планом робіт, а не із загальними словами, нам потрібен мінімум вхідних даних про ваш продукт. Імпорт приватного ключа зачіпає одразу кілька шарів: криптографію, зберігання секретів, інтерфейс і сумісність із уже наявними гаманцями.
Чим точніше ви опишете поточний стан, тим менше припущень закладемо в план і тим передбачуванішим буде результат.
- Які формати ключів і мнемонік потрібно підтримати: hex, WIF, BIP-39, keystore-файли, апаратні сховища — і в якому вигляді користувач їх отримує.
- Які мережі та типи акаунтів у пріоритеті: одна мережа чи кілька, чи потрібні адреси різних стандартів з одного ключа.
- Де зараз зберігаються секрети: системний захищений контейнер, шифрування паролем, біометрія — і які вимоги до захисту ви закладаєте.
- Як влаштовано введення: ручне введення, сканування QR, вставлення з буфера, імпорт файлу — і що відбувається при помилці чи дублікаті.
- Чи є вже працюючий гаманець, з якого користувачі переноситимуть ключі, і чи потрібна зворотна сумісність.
- Платформи та мінімальні версії систем, на які орієнтуєтеся, а також вимоги магазинів застосунків до роботи з ключами.
- Що для вас критично в строках: запуск до дати, поетапне викочування чи спочатку перевірка на обмеженій аудиторії.
На виході ви отримаєте оцінку трудовитрат за етапами, план робіт із порядком реалізації та точками перевірки, схему зберігання й обробки ключа, а також перелік ризиків із варіантами їх закриття.
Окремо проговоримо, як буде влаштовано відкат і що потрапить у першу версію, а що можна винести в другу.
Опишіть завдання у вільній формі — що вже є, що потрібно додати і до якого результату йдете. Повернемося з оцінкою та планом робіт, а наступний крок узгодимо після того, як звіримо деталі.
