Серия «Keychain на iOS» (будет дополняться по мере выхода статей):
Keychain на iOS, часть 2. Когда Keychain не отдаст секрет (вы здесь)
Мы привыкли, что приложение помнит нас. Пользователи современных банковских приложений вряд ли вспомнят, когда в последний раз вводили пароль, и внезапный экран ввода пароля выглядит как сбой. Заметить эту проблему трудно: у разработчика она не воспроизводится, тестирование до такого случая обычно не доходит из-за его редкости, а пользователи жалуются не всегда, поэтому о ней обычно узнают довольно поздно. Но обратить внимание на такую проблему нужно, ведь все мы строим идеальный продукт и каждый из пользователей должен быть доволен им.
Токен в этой статье означает строку, которую сервер выдаёт после аутентификации, чтобы не спрашивать пароль при каждом запросе. Фоновой работой будем называть ситуацию, когда iOS на несколько секунд запускает приложение без ведома пользователя, например после push-уведомления, и экран при этом выключен. Код-пароль знаком каждому владельцу iPhone - это шестизначный пин, который вы вводите на телефоне, и дальше речь пойдёт именно о нём.
Проблема, с которой сталкиваются почти все
Допустим, у вас мессенджер. Пользователь вошёл в аккаунт, токен лёг в Keychain, всё работает. Ночью телефон перезагрузился из-за обновления iOS и лежит на тумбочке с экраном приветствия, куда нужно ввести код-пароль. Тем временем на сервер приходит новое сообщение, сервер шлёт push, iOS запускает приложение в фоне на пару секунд, чтобы оно подтянуло свежие данные. Приложение идёт в Keychain за токеном и получает ошибку errSecInteractionNotAllowed. Многие разработчики на этом месте решают, что токена нет, и отправляют пользователя на экран входа. Утром он видит просьбу ввести пароль заново, хотя ничего не менял, и пишет в поддержку, что приложение его разлогинило без видимых на то причин. Токен при этом никуда не пропадал, он лежал на месте, но система в тот момент не имела права его расшифровать. Код приложения принял временный запрет за отсутствие записи. Ошибок здесь две, и обрабатывать их нужно по-разному. errSecItemNotFound означает «такой записи нет». errSecInteractionNotAllowed означает «отдать секрет сейчас нет возможности, попробуйте позже». До первой разблокировки по второму статусу не видно, лежит запись на месте или её ещё не создавали, но экран входа из-за него показывать нельзя в любом случае.
Почему запись в Keychain может быть недоступна
Чтобы понять причину, придётся немного углубиться в устройство ключей. Keychain на iPhone зашифрован, и ключи шифрования устроены как иерархия, в которой каждый уровень открывает следующий. В основании лежит комбинация вашего код-пароля и секрета, который зашит в процессор при производстве и который невозможно извлечь, он называется UID. Из этой комбинации система вычисляет ключи классов защиты, и именно они расшифровывают конкретные записи. Подробно устройство описано в разделе Keychain data protection руководства Apple по безопасности платформ, а набор ключей, который система держит в памяти, называется keybag, о нём рассказывает страница Keybags for Data Protection.
Часть ключей система стирает из оперативной памяти, когда телефон блокируется, и без ввода код-пароля или Face ID восстановить их нельзя. Пока ключа нет, запись, зашифрованная именно им, остаётся нечитаемым набором байтов, и приложение здесь бессильно. Поведение задумано так: если вор достал телефон из кармана спящим, он не получит ваши токены только потому, что запустил на нём ваше приложение или подключил его к компьютеру. Блокировка здесь настоящая: запись остаётся на накопителе, однако у операционной системы в этот момент отсутствует материал, который нужен для расшифровки, так что попытка достать секрет не может превратиться в обход защиты из-за ошибки в коде разработчика. Даже процесс приложения, которому эта запись принадлежит, получит отказ до следующей успешной разблокировки.
Сохраняя запись, вы выбираете, каким ключом её запереть, и тем самым выбираете, в какие моменты она будет читаться. Выбор делается одним атрибутом, kSecAttrAccessible.
Три состояния телефона
Для разговора о доступности хватает трёх состояний устройства. Сразу после включения или перезагрузки владелец ещё ни разу не вводил код-пароль, и иногда такое состояние называют «до первой разблокировки». Когда телефон разблокирован, экран горит и пользователь им пользуется. Если же после включения его разблокировали хотя бы раз, а потом он заблокировался кнопкой или по таймеру, он оказывается в состоянии, которое в документации называют «после первой разблокировки», и проводит в нём большую часть жизни, лёжа на столе, заряжаясь и принимая push-уведомления. Между разблокированным телефоном и телефоном «после первой разблокировки» есть тонкость, из-за которой возникает больше всего путаницы. Если запись под ключом класса «только когда разблокировано», то в последнем состоянии она недоступна, хотя телефон давно включён и прекрасно работает. Ключ класса «после первой разблокировки» ведёт себя иначе: он остаётся в памяти до следующей перезагрузки, поэтому такие записи читаются и при заблокированном экране.
Какие значения доступности в Keychain бывают
Ниже все значения kSecAttrAccessible, которые стоит знать, и для каждого указано, когда запись читается, переезжает ли она на другое устройство через резервную копию или синхронизацию и для чего её обычно выбирают. Слово «переезжает» значит, что запись может оказаться на другом телефоне пользователя, например после покупки нового, и это возможно двумя путями. Записи попадают на новый телефон при восстановлении локальной копии, которую делали на компьютере через Finder, но только если копия зашифрована паролем: без пароля записи Keychain на новом телефоне не появятся. Другой путь это синхронизация через iCloud Keychain, она работает только для записей, которые приложение явно пометило атрибутом kSecAttrSynchronizable, и она по умолчанию выключена. Резервная копия в iCloud записи на другой телефон не переносит: локальный Keychain в ней зашифрован ключом, привязанным к самому устройству. Записи с суффиксом ThisDeviceOnly не переезжают никуда: из резервной копии их можно вернуть только на тот же телефон, а синхронизироваться они не могут. Подробно про синхронизацию и резервные копии поговорим в пятой части.
kSecAttrAccessibleWhenUnlocked читается только при разблокированном телефоне, переезжает на другое устройство и подходит для паролей, которые нужны, пока человек смотрит в экран. kSecAttrAccessibleAfterFirstUnlock читается после первой разблокировки до перезагрузки, тоже переезжает и нужен для токенов, которые читаются в фоне.
Отдельно стоит kSecAttrAccessibleWhenPasscodeSetThisDeviceOnly: запись читается только при разблокированном телефоне и только если задан код-пароль, никуда не переезжает, а выбирают это значение для самых чувствительных секретов.
Два старых значения, kSecAttrAccessibleAlways и kSecAttrAccessibleAlwaysThisDeviceOnly, отдавали запись даже до первой разблокировки. Apple пометила их устаревшими начиная с iOS 12, и в новых проектах они не нужны. Актуальный список значений смотрите на странице kSecAttrAccessible, потому что документация обновляется.
Если вы вообще не указали kSecAttrAccessible, система выберет значение по умолчанию, и это kSecAttrAccessibleWhenUnlocked.
Пример хранилища токена
Ниже небольшое хранилище для токена, которое явно задаёт доступность и различает два вида ошибок из начала статьи. Идентификаторы service и account в примере выдуманные, подставьте свои.
import Foundation import Security enum TokenStoreError: Error { /// Пары service + account в Keychain нет. Сессии нет, можно показать вход. case notFound /// errSecInteractionNotAllowed (-25308). /// Система не отдаёт секрет: ключа класса защиты сейчас нет в памяти. /// До первой разблокировки так отвечает и запрос записи, которой нет, /// поэтому этот статус не доказательство, что токен на месте. /// Экран входа из-за него показывать нельзя. Повторить чтение, когда /// защищённые данные снова доступны (isProtectedDataAvailable), /// а не когда просто загорится экран. case lockedDevice /// SecItemCopyMatching вернул errSecSuccess, но байты не строка токена. /// Статус при этом 0, поэтому класть его в system нельзя. case corrupt case system(OSStatus) } struct TokenStore { private let service = "com.example.app.auth" private let account = "refresh-token" /// Адрес записи. Секрет и kSecAttrAccessible сюда не входят. /// Если положить класс защиты в поисковый словарь, токен, сохранённый /// раньше с другим классом, не найдётся, и read превратится в notFound. private var baseQuery: [String: Any] { [ kSecClass as String: kSecClassGenericPassword, kSecAttrService as String: service, kSecAttrAccount as String: account ] } func save(_ token: String) throws { let data = Data(token.utf8) /// Словарь изменений, не поиска. Класс защиты обновляется вместе с секретом, /// поэтому запись, созданная с дефолтным WhenUnlocked, переезжает /// на AfterFirstUnlockThisDeviceOnly. Пока старая запись недоступна, /// update вернёт lockedDevice и не сотрёт токен. let changes: [String: Any] = [ kSecValueData as String: data, kSecAttrAccessible as String: kSecAttrAccessibleAfterFirstUnlockThisDeviceOnly ] switch SecItemUpdate(baseQuery as CFDictionary, changes as CFDictionary) { case errSecSuccess: return case errSecInteractionNotAllowed: throw TokenStoreError.lockedDevice case errSecItemNotFound: break case let status: throw TokenStoreError.system(status) } var addQuery = baseQuery addQuery.merge(changes) { _, new in new } switch SecItemAdd(addQuery as CFDictionary, nil) { case errSecSuccess: return case errSecInteractionNotAllowed: /// До первой разблокировки запись нельзя и создать: /// ключа, которым её шифруют, ещё нет в памяти. throw TokenStoreError.lockedDevice case errSecDuplicateItem: /// Update не нашёл запись, Add нашёл. Другая задача успела создать её /// между двумя вызовами. Пишем своё значение повторным update. switch SecItemUpdate(baseQuery as CFDictionary, changes as CFDictionary) { case errSecSuccess: return case errSecInteractionNotAllowed: throw TokenStoreError.lockedDevice case let status: throw TokenStoreError.system(status) } case let status: throw TokenStoreError.system(status) } } func read() throws -> String { var query = baseQuery query[kSecReturnData as String] = true query[kSecMatchLimit as String] = kSecMatchLimitOne var result: CFTypeRef? let status = SecItemCopyMatching(query as CFDictionary, &result) switch status { case errSecSuccess: guard let data = result as? Data, let token = String(data: data, encoding: .utf8) else { throw TokenStoreError.corrupt } return token case errSecItemNotFound: throw TokenStoreError.notFound case errSecInteractionNotAllowed: throw TokenStoreError.lockedDevice default: throw TokenStoreError.system(status) } } /// Выход из аккаунта. Повторный вызов не ошибка: секрета уже нет. /// lockedDevice здесь значит, что стереть токен не удалось и он всё ещё лежит. func delete() throws { let status = SecItemDelete(baseQuery as CFDictionary) switch status { case errSecSuccess, errSecItemNotFound: return case errSecInteractionNotAllowed: throw TokenStoreError.lockedDevice default: throw TokenStoreError.system(status) } } }
Словарь baseQuery описывает, какую именно запись мы ищем: класс «универсальный пароль» плюс пара service и account, вместе они работают как адрес. Секрет и kSecAttrAccessible лежат в отдельном словаре changes, а не в поиске. Класс защиты в поисковом словаре отсечёт запись, сохранённую с другим значением, и read вернёт notFound, хотя токен на месте. Метод save сначала вызывает SecItemUpdate и передаёт в changes новое значение секрета вместе с kSecAttrAccessibleAfterFirstUnlockThisDeviceOnly. Атрибут доступности записывается и при создании, и при обновлении. Если токен когда-то сохранили без явного класса, система выбрала WhenUnlocked, и успешный save переводит запись на класс для фоновой работы. Перевод проходит только пока запись читается: для старого WhenUnlocked это разблокированный телефон, поэтому миграция происходит при сохранении на переднем плане. Пока запись недоступна, SecItemUpdate возвращает lockedDevice и не трогает прежний токен. Ответ errSecItemNotFound означает, что записи ещё нет, и тогда save создаёт её через SecItemAdd с тем же changes. До первой разблокировки создать запись тоже нельзя: ключа, которым она шифруется, ещё нет в памяти, и SecItemAdd вернёт lockedDevice. Если запись уже была, повторное добавление не вызывается. Если другая задача успеет создать её между SecItemUpdate и SecItemAdd, добавление вернёт errSecDuplicateItem, и save ещё раз вызовет SecItemUpdate, чтобы записать наш токен. Подробно операции создания, чтения, обновления и удаления мы разберём в третьей части. Пока запомните практическое правило: параметры, которые описывают саму запись, например сервис и аккаунт, кладут в поисковый словарь, а новое значение секрета и настройки, которые нужно поменять, передают отдельным словарём в SecItemUpdate. Если смешать эти роли, ошибка обычно выглядит загадочно, хотя причина всего лишь в неверном запросе.
Метод read интересен веткой errSecInteractionNotAllowed. Мы превращаем её в отдельную ошибку lockedDevice: Keychain не отдал секрет, потому что ключа класса защиты сейчас нет в памяти. До первой разблокировки после включения тот же статус приходит и тогда, когда токен ещё ни разу не сохраняли. По одному errSecInteractionNotAllowed не видно, лежит запись на месте или её ещё нет. Вызывающий код в любом случае не показывает экран входа и откладывает работу до возвращения защищённых данных. Смотреть нужно на UIApplication.isProtectedDataAvailable и на уведомление UIApplication.protectedDataDidBecomeAvailableNotification. Для класса AfterFirstUnlock флаг становится истинным после первого ввода код-пароля и остаётся таким до следующей перезагрузки, в том числе при выключенном экране. Когда защищённые данные снова доступны, повторный read либо вернёт токен, либо даст уже честный notFound. Если Keychain ответил успехом, но из байтов не получается строка, read бросает corrupt. Статус операции при этом errSecSuccess, ноль, и относить такой ответ к system или к отсутствию сессии нельзя. Рядом в хранилище есть delete для выхода из аккаунта. Повторное удаление ошибкой не считается: errSecItemNotFound значит, что секрета уже нет. lockedDevice при удалении значит, что токен стереть не удалось и он по-прежнему хранится в Keychain.
Как воспроизвести отказ Keychain на своём телефоне
Отказ, о котором шла речь в начале статьи, это errSecInteractionNotAllowed: в нашем хранилище он превращается в lockedDevice. Приложение получает его, когда ключа класса защиты нет в памяти, и воспроизвести это на своём телефоне несложно. На симуляторе не получится: он не воспроизводит блокировку с настоящим шифрованием ключей, поэтому там записи читаются всегда. Нужен реальный iPhone с включённым код-паролем. Временно замените в save класс на kSecAttrAccessibleWhenUnlocked и сохраните токен, а затем добавьте в приложение кнопку, которая через десять секунд вызывает read() в фоновой задаче и пишет результат в лог или в локальное уведомление. Нажмите кнопку, заблокируйте телефон и дождитесь результата: с WhenUnlocked вы получите lockedDevice, а с AfterFirstUnlock токен вернётся нормально.
Отдельно стоит проверить вариант «до первой разблокировки»: он ближе всего к ночной истории с обновлением системы из начала статьи. Перезагрузите телефон и не вводите пароль. Приложение при этом должно запуститься в фоне, например от push с флагом content-available, и прочитать токен. Для записей с WhenUnlocked и с AfterFirstUnlock вы увидите lockedDevice, а после первой разблокировки запись с AfterFirstUnlock прочитается. Это неудобный тест, но именно такой сценарий ломает логику приложения в реальной жизни, и один раз пройти его стоит. Проверку нельзя подменить unit-тестом: он полезен для построения запроса и обработки статусов, однако не может воспроизвести ключи, которые iOS выгружает после блокировки. В плане тестирования такой запуск на физическом телефоне должен быть отдельным пунктом перед релизом.
Три частых заблуждения
«Если я помещу запись в Keychain, она всегда будет защищена одинаково». Защита зависит от выбранного класса и от того, как давно и как осмысленно человек разблокировал телефон. Запись с AfterFirstUnlock будет легко доступна на разблокированном и заблокированном устройстве, если после включения один раз введён код-пароль. Для атакующего, который уже запустил свой код на разблокированном телефоне или взломал само приложение, это уже другая задача, и от неё классы доступности не спасут.
«Раз на симуляторе всё работает, на боевом устройстве проблем не будет». Симулятор не воспроизводит блокировку с настоящим шифрованием ключей, поэтому записи там читаются всегда, и проблема с блокировкой на нём не проявляется.
«После удаления и повторной установки Keychain очищается». В общем случае записи могут пережить удаление приложения, поэтому важно дать пользователю явный выход из аккаунта, который удаляет секреты, а на первом запуске после установки стоит проверять, не остались ли старые записи. Подробнее про переустановку было в первой части, там же ссылки на официальные источники.
В следующей части разберём устройство самих записей: какие бывают классы, какие атрибуты образуют адрес записи и как написать полноценный слой доступа к Keychain с созданием, чтением, обновлением и удалением.
