feat: Implement BiometricAuthManager for biometric authentication and password encryption/decryption

2026-01-22 14:26:30 +05:00
parent 727ae9b5b5
commit f6f8620102
8 changed files with 1094 additions and 142 deletions
--- a/docs/BIOMETRIC_AUTHENTICATION.md
+++ b/docs/BIOMETRIC_AUTHENTICATION.md
@@ -0,0 +1,206 @@
+# Биометрическая аутентификация в Rosetta Messenger
+
+## Обзор
+
+В Android-приложение добавлена поддержка биометрической аутентификации (отпечаток пальца / Face ID), что позволяет пользователям разблокировать приложение без ввода пароля каждый раз.
+
+## Особенности реализации
+
+### 1. Безопасность
+
+- **Android Keystore**: Пароль шифруется с использованием ключа, хранящегося в Android Keystore
+- **Биометрическая защита**: Ключ требует биометрической аутентификации для расшифровки
+- **GCM шифрование**: Используется AES-GCM для шифрования пароля
+- **Автоматическая инвалидация**: При изменении биометрических данных ключ становится недействительным
+
+### 2. Компоненты
+
+#### BiometricAuthManager
+
+Основной менеджер для работы с биометрией:
+
+- `isBiometricAvailable()` - проверка доступности биометрии на устройстве
+- `encryptPassword()` - шифрование пароля с биометрической защитой
+- `decryptPassword()` - расшифровка пароля через биометрию
+- `removeBiometricData()` - удаление сохраненных данных
+
+#### BiometricPreferences
+
+Управление настройками биометрии:
+
+- Сохранение зашифрованных паролей для каждого аккаунта
+- Включение/отключение биометрии
+- Проверка наличия сохраненных данных
+
+#### Интеграция в UnlockScreen
+
+- Автоматическая попытка разблокировки при открытии экрана
+- Кнопка для включения/отключения биометрии
+- Автоматическое сохранение пароля после успешного входа
+
+### 3. Пользовательский опыт
+
+#### Первое использование
+
+1. Пользователь вводит пароль для разблокировки
+2. Если биометрия доступна, появляется опция "Включить биометрию"
+3. При включении пароль сохраняется зашифрованным
+4. При следующем входе автоматически появляется диалог биометрии
+
+#### Автоматическая разблокировка
+
+- При открытии экрана разблокировки автоматически запускается биометрическая аутентификация
+- Пользователь может отменить и ввести пароль вручную
+- При неудаче биометрии доступен ввод пароля
+
+#### Управление
+
+- Переключатель "Биометрия включена / Включить биометрию" под кнопкой Unlock
+- При отключении зашифрованный пароль удаляется
+- Можно включить/отключить в любой момент
+
+### 4. Поддерживаемые методы
+
+- **Отпечаток пальца** (Fingerprint)
+- **Face ID** (на устройствах с поддержкой)
+- **Iris** (на поддерживаемых устройствах)
+- Любые другие биометрические методы, поддерживаемые Android BiometricPrompt
+
+### 5. Требования
+
+- Android API 24+ (Android 7.0)
+- Устройство с биометрическим оборудованием
+- Настроенные биометрические данные в системе
+- Разрешение `USE_BIOMETRIC` (добавлено в AndroidManifest.xml)
+
+## Технические детали
+
+### Зависимости
+
+```kotlin
+implementation("androidx.biometric:biometric:1.1.0")
+```
+
+### Разрешения
+
+```xml
+<uses-permission android:name="android.permission.USE_BIOMETRIC" />
+```
+
+### Хранение данных
+
+- Зашифрованные пароли хранятся в DataStore
+- Отдельный пароль для каждого аккаунта
+- Формат: `encrypted_password_{publicKey}`
+
+### Шифрование
+
+- **Алгоритм**: AES/GCM/NoPadding
+- **Размер ключа**: 256 бит
+- **Хранилище**: Android Keystore
+- **IV**: Генерируется для каждого шифрования
+
+## Использование
+
+### Для разработчиков
+
+#### Проверка доступности биометрии
+
+```kotlin
+val biometricManager = BiometricAuthManager(context)
+when (biometricManager.isBiometricAvailable()) {
+    BiometricAvailability.Available -> {
+        // Биометрия доступна
+    }
+    is BiometricAvailability.NotAvailable -> {
+        // Недоступна (причина в reason)
+    }
+    is BiometricAvailability.NotEnrolled -> {
+        // Биометрия не настроена
+    }
+}
+```
+
+#### Шифрование пароля
+
+```kotlin
+biometricManager.encryptPassword(
+    activity = activity,
+    password = userPassword,
+    onSuccess = { encryptedPassword ->
+        // Сохранить зашифрованный пароль
+    },
+    onError = { errorMessage ->
+        // Обработка ошибки
+    },
+    onCancel = {
+        // Пользователь отменил
+    }
+)
+```
+
+#### Расшифровка пароля
+
+```kotlin
+biometricManager.decryptPassword(
+    activity = activity,
+    encryptedData = savedEncryptedPassword,
+    onSuccess = { decryptedPassword ->
+        // Использовать пароль для входа
+    },
+    onError = { errorMessage ->
+        // Показать ошибку
+    },
+    onCancel = {
+        // Показать ввод пароля
+    }
+)
+```
+
+## Безопасность
+
+### Что защищено
+
+✅ Пароль никогда не хранится в открытом виде  
+✅ Ключ шифрования защищен биометрией  
+✅ Ключ недействителен после смены биометрических данных  
+✅ Требуется подтверждение для каждой расшифровки
+
+### Что НЕ защищено
+
+❌ Root-доступ может скомпрометировать Keystore  
+❌ Вредоносное ПО с правами администратора
+
+## Тестирование
+
+### Эмулятор
+
+1. Settings → Security → Fingerprint
+2. Добавить отпечаток
+3. В терминале эмулятора: `adb -e emu finger touch 1`
+
+### Реальное устройство
+
+1. Настроить биометрию в системных настройках
+2. Запустить приложение
+3. Войти с паролем
+4. Включить биометрию
+5. Перезапустить приложение
+
+## Известные ограничения
+
+1. **Множественные аккаунты**: Биометрия настраивается отдельно для каждого аккаунта
+2. **Смена биометрии**: При изменении отпечатков/Face ID нужно заново включить биометрию
+3. **Фоновая работа**: Биометрия работает только когда приложение активно
+
+## Будущие улучшения
+
+- [ ] Настройка в профиле пользователя
+- [ ] Опция "Всегда спрашивать биометрию"
+- [ ] Статистика использования биометрии
+- [ ] Поддержка PIN-кода как альтернативы
+- [ ] Экспорт/импорт настроек биометрии
+
+## Заключение
+
+Биометрическая аутентификация значительно улучшает пользовательский опыт, позволяя быстро и безопасно разблокировать приложение. Реализация следует лучшим практикам Android Security и использует надежные криптографические методы.
--- a/docs/BIOMETRIC_USER_GUIDE_RU.md
+++ b/docs/BIOMETRIC_USER_GUIDE_RU.md
@@ -0,0 +1,79 @@
+# Как использовать биометрическую аутентификацию
+
+## Первичная настройка
+
+1. **Откройте приложение и войдите с паролем**
+   - Выберите свой аккаунт
+   - Введите пароль
+   - Нажмите "Unlock"
+
+2. **Включите биометрию**
+   - Под кнопкой "Unlock" появится опция "Включить биометрию"
+   - Нажмите на неё
+   - Биометрия будет включена
+
+3. **Готово!**
+   - При следующем входе приложение автоматически предложит использовать отпечаток пальца / Face ID
+   - Больше не нужно вводить пароль
+
+## Вход с биометрией
+
+1. **Откройте приложение**
+   - Автоматически появится диалог биометрической аутентификации
+2. **Подтвердите биометрию**
+   - Приложите палец к сканеру или посмотрите в камеру
+   - Приложение разблокируется автоматически
+
+3. **Альтернатива**
+   - Можно нажать "Использовать пароль" в диалоге биометрии
+   - Или отключить биометрию и ввести пароль вручную
+
+## Отключение биометрии
+
+1. **На экране входа**
+   - Нажмите на переключатель "Биометрия включена"
+   - Биометрия будет отключена
+   - Зашифрованный пароль будет удален
+
+2. **При следующем входе**
+   - Нужно будет ввести пароль вручную
+
+## Требования
+
+- Устройство должно поддерживать биометрическую аутентификацию
+- В настройках системы должны быть настроены отпечаток пальца или Face ID
+- Android 7.0 или новее
+
+## Безопасность
+
+✅ **Ваш пароль надежно защищен**
+
+- Пароль шифруется специальным ключом в Android Keystore
+- Расшифровка возможна только через биометрию
+- При смене отпечатков/Face ID нужно заново включить биометрию
+
+✅ **Конфиденциальность**
+
+- Биометрические данные хранятся только в системе Android
+- Приложение не имеет доступа к вашим отпечаткам
+- Используется только для подтверждения личности
+
+## Troubleshooting
+
+### Биометрия не работает
+
+- Убедитесь, что биометрия настроена в системных настройках
+- Попробуйте отключить и снова включить биометрию в приложении
+- Проверьте, что сканер отпечатков чистый
+
+### Приложение не предлагает биометрию
+
+- Возможно, устройство не поддерживает биометрию
+- Убедитесь, что добавлен хотя бы один отпечаток/Face ID в системных настройках
+- Попробуйте перезапустить приложение
+
+### После обновления системы биометрия не работает
+
+- Это нормально при смене биометрических данных
+- Войдите с паролем
+- Заново включите биометрию