avbroot

avbroot – это утилита для воспроизводимой модификации OTA-образов Android A/B-формата и их переподписания пользовательскими ключами. Она также включает в себя набор подкоманд для упаковки и распаковки образов Android различных форматов.

Прежде чем использовать avbroot, рекомендуется иметь хорошее понимание того, как работают AVB и OTA в формате A/B. Как минимум, следует ознакомиться с разделом предостережений, чтобы избежать хардбрика устройства.

Требования

• Поддерживаются только устройства, использующие современную A/B-разметку. Это большинство девайсов, выпускаемых с Android 10 и новее (за исключением устройств от Samsung). Чтобы проверить, использует ли ваше устройство необходимую схему разметки, откройте zip-архив OTA и проверьте:

• наличие файла payload.bin (обычно находится в корне архива)

• наличие файла META-INF/com/android/metadata (Android 10-11) или META-INF/com/android/metadata.pb (Android 12+)

• Устройство должно поддерживать установку пользовательского публичного ключа для подтверждения статуса доверия загрузчика. Обычно это производится с помощью команды fastboot flash avb_custom_key.

Список девайсов, на которых проверялась совместимость с указанным выше функционалом, находится здесь: #299.

Патчи

avbroot модифицирует следующие образы:

• boot или init_boot, в зависимости от устройства, модифицируется для получения root-доступа, если это запрашивается.

• boot, recovery или vendor_boot, в зависимости от устройства, модифицируется для замены сертификата проверки подписи OTA на пользовательский. Это позволяет устанавливать будущие пропатченные OTA через режим Recovery уже после блокировки загрузчика, то есть в качестве обновления. Также это предотвращает случайную установку оригинального непропатченного OTA.

• system тоже модифицируется для замены сертификата проверки подписи OTA. Это не позволит системному приложению обновлений ОС установить оригинальный непропатченный OTA и дает возможность использовать сторонние приложения для установки пропатченных OTA.

Предостережения

• Всегда оставляйте опцию Заводской разблокировки (или OEM unlocking в англ.) включенной при наличии root-прав с заблокированным загрузчиком. Это очень важно. Доступ к root-правам потенциально позволяет перезаписать загрузочный раздел из-под системы, будь то сделано случайно или намеренно, файлом, который не был подписан должным образом. В таком случае, система и режим Recovery больше не смогут загрузиться, а команда fastboot flashing unlock будет недоступна, потому что параметр Заводской разблокировки отключен. То есть, это приведет к хардбрику устройства.

  Повторюсь: ВСЕГДА оставляйте Заводскую разблокировку включенной при наличии root-прав.

• Любая операция, приводящая к прошивке некорректно подписанного загрузочного образа, приведет к тому, что устройство больше не сможет загрузиться в систему/режим Recovery, а для его восстановления потребуется повторная разблокировка загрузчика (и, следовательно, стирание всех пользовательских данных). К подобным операциям в том числе относятся:

  • Метод Прямой установки для обновления Magisk. Magisk можно обновлять только путем репатчинга OTA, но не через его приложение.

  • Функция Удаление Magisk в приложении Magisk. Если вам больше не нужен root-доступ, Magisk должен быть удален путем репатчинга OTA с использованием параметра --rootless, но не через его приложение.

  Если в загрузочный раздел были внесены какие-либо изменения, не перезагружайтесь. Обратитесь за помощью, открыв Issue, и четко разъясните, какие конкретные действия привели к возникновению такой ситуации. Если Android всё еще работает и доступ к root-правам сохранился – вероятно, получится откатить изменения до исходного состояния, не стирая ваши данные.

Использование

1. Убедитесь, что вы ознакомились и поняли указанные выше предостережения.

2. Скачайте последнюю версию со страницы релизов. Чтобы сверить цифровую подпись, см. раздел проверки цифровых подписей.

   avbroot – это отдельный исполняемый файл. Он не требует установки и может быть запущен из любого места на диске.

3. Сгенерируйте ключи подписи.

Пропустите этот шаг, если вы обновляете Android, Magisk или KernelSU уже после выполнения первоначальной настройки. Повторная генерация ключей подписи для обновлений не требуется: для всех последующих обновлений должны использоваться те ключи, что были созданы при первоначальной настройке.

1. Пропатчите ОТА-архив с помощью команды:

   bash avbroot ota patch \ --input /путь/к/ota.zip \ --key-avb /путь/к/avb.key \ --key-ota /путь/к/ota.key \ --cert-ota /путь/к/ota.crt \

   Добавьте следующие аргументы в конец команды в зависимости от того, как вы хотите получить root-доступ.

   • Для получения root-доступа с использованием Magisk:

     bash --magisk /путь/к/magisk.apk \ --magisk-preinit-device <имя>

     Если вы не знаете имени раздела предварительной инициализации Magisk, следуйте инструкции в соответствующем разделе.

     Если вы пропатчили загрузочный образ вручную через приложение Magisk (вместо автоматического идентичного патчинга через avbroot), используйте следующий аргумент:

     bash --prepatched /путь/к/magisk_patched-xxxxx_yyyyy.img

   • Для получения root-доступа с использованием KernelSU:

     bash --prepatched /путь/к/kernelsu_boot.img

   • Без root-доступа:

     bash --rootless

   Больше информации про существующие аргументы можно найти в разделе расширенного использования.

   Если название для --output не указывается, то готовый файл будет записан как <название-ota-zip-в-input>.patched.

2. Готово! Для прошивки пропатченного OTA следуйте инструкции в разделе первоначальной настройки. Для последующих обновлений тоже есть соответствующий раздел обновлений.

Генерация ключей

Во время патчинга OTA, avbroot подписывает несколько компонентов:

• загрузочный образ (boot)
• образ vbmeta
• payload из OTA
• сам архив OTA

Первые два компонента подписываются ключом AVB, а последние два – ключом OTA. Можно использовать один и тот же ключ, однако в следующих шагах описано, как сгенерировать два отдельных.

Если вы патчите OTA сразу для нескольких устройств, настоятельно рекомендуется генерировать уникальные ключи для каждого девайса – так вы защитите себя от случайной прошивки неподходящего OTA.

1. Сгенерируйте ключи подписи для AVB и OTA.

   bash avbroot key generate-key -o avb.key avbroot key generate-key -o ota.key

2. Преобразуйте публичную часть ключа подписи AVB в формат метаданных публичного ключа AVB. Именно этот формат используется в загрузчике устройства для установки пользовательского ключа.

   bash avbroot key encode-avb -k avb.key -o avb_pkmd.bin

3. Сгенерируйте самоподписанный сертификат для ключа подписи OTA. Он используется режимом Recovery для проверки подписи OTA при установке обновления.

   bash avbroot key generate-cert -k ota.key -o ota.crt

avbroot совместим с любым стандартным 4096-битным приватным ключом RSA в кодировке PKCS#8 и сертификатом X509 в кодировке PEM, например с теми, которые генерируются openssl.

Если вы потеряете ключ(-и) подписи AVB или OTA, вы больше не сможете подписывать новые OTA-архивы. Придется генерировать новые ключи подписи и разблокировать загрузчик (что приведет к стиранию всех данных). В таком случае возвращайтесь к инструкции в разделе использования.

Первоначальная настройка

1. Убедитесь, что вы используете утилиту fastboot версии 35 или новее. Предыдущие версии содержат баги, что не позволяют команде fastboot flashall (которая понадобится по ходу инструкции) работать правильно.

   bash fastboot --version

2. Перезагрузитесь в режим fastboot и разблокируйте загрузчик, если не сделали этого ранее. Это приведет к стиранию всех пользовательских данных.

   bash fastboot flashing unlock

3. Перед первой установкой, на устройстве уже должна быть установлена в оригинальном виде та прошивка, пропатченную версию которой вы собираетесь ставить. Если это не так, сначала установите оригинальную непропатченную OTA.

4. Извлекаем из пропатченного OTA модифицированные образы:

   bash avbroot ota extract \ --input /путь/к/ota.zip.patched \ --directory extracted \ --fastboot

   Если вы на всякий случай хотите прошить вообще все разделы из ОТА, извлечь их можно, указав аргумент --all.

5. Установите переменную окружения ANDROID_PRODUCT_OUT, указав директорию с извлеченными файлами.

   Для sh/bash/zsh (Linux, macOS, WSL):

   bash export ANDROID_PRODUCT_OUT=extracted

   Для PowerShell (Windows):

   powershell $env:ANDROID_PRODUCT_OUT = "extracted"

   Для cmd (Командная строка или Терминал) (Windows):

   bat set ANDROID_PRODUCT_OUT=extracted

6. Прошейте извлеченные образы разделов.

   bash fastboot flashall --skip-reboot

   Обратите внимание, что так прошиваются лишь те образы, что относятся к системе. Разделы загрузчика и модема же остаются нетронутыми из-за ограничений fastboot. Если они не обновлены до необходимой версии, или вы не уверены в этом, после прошивки перейдите к пункту обновлений и установите пропатченный OTA в режиме Recovery. Прошивка полного OTA гарантирует, что абсолютно все разделы будут обновлены.

   Для устройств Pixel есть ещё один вариант: запуск скрипта flash-base.sh из папки заводских образов (factory images) обновит загрузчик и модем.

7. После перезагрузки из fastbootd в загрузчик (bootloader), установите пользовательский публичный ключ AVB в загрузчик:

   bash fastboot reboot-bootloader fastboot erase avb_custom_key fastboot flash avb_custom_key /путь/к/avb_pkmd.bin

8. [Опционально] Перед блокировкой загрузчика загрузитесь в систему, дабы убедиться, что все подписано правильно.

   Установите приложение Magisk или KernelSU и выполните следующую команду:

   bash adb shell su -c 'dmesg | grep libfs_avb'

   Если AVB работает корректно, будет выведено следующее сообщение:

   bash init: [libfs_avb]Returning avb_handle with status: Success

   Как ещё один вариант, Android-версию avbroot также можно использовать для проверки разделов на устройстве.

9. Перезагрузитесь в fastboot и заблокируйте загрузчик. Это снова приведет к стиранию данных.

   bash fastboot flashing lock

   Подтвердите нажатием клавиш уменьшения громкости и включения, а после перезагрузитесь в систему.

   Напоминаю: не отключайте Заводскую разблокировку!

   ПРЕДУПРЕЖДЕНИЕ: Если вы прошили CalyxOS, мастер настройки автоматически отключит опцию Заводской разблокировки. Не забудьте снова включить её вручную в настройках для разработчиков. Для перестраховки можете использовать модуль OEMUnlockOnBoot, который автоматически включает пункт Заводской разблокировки при каждом запуске системы.

10. Готово! Установка последующих обновлений системы, Magisk или KernelSU, описывается в следующем разделе.

Обновления

Обновления Android, Magisk и KernelSU выполняются одинаково – исключительно путем обновления или репатчинга того же самого OTA.

1. Сгенерируйте новый пропатченный OTA согласно инструкции в разделе использования.

2. Если обновляется Magisk или KernelSU, сначала установите их новый .apk. Если вы случайно открыли приложение, убедитесь, что оно не начало прошивать загрузочный образ. Если в самом приложении появится предложение обновить загрузочный образ, отклоните его.

3. Перезагрузитесь в режим Recovery: adb reboot recovery. Если устройство повисло на сплеше с сообщением "No command", удерживайте кнопку питания, а затем один раз нажмите кнопку увеличения громкости.

4. Обновитесь (Apply update from adb → adb sideload <ota.zip.patched>).

5. Перезагрузите устройство. Обратите внимание, что при первом запуске после обновления ОС устройство может загружаться дольше обычного (иногда до нескольких минут).

ПРЕДУПРЕЖДЕНИЕ: В силу специфики работы виртуального A/B в Android, сразу после установки OTA и перезагрузки, в фоновом режиме незаметно запускается операция слияния снапшотов. Во время этого процесса невозможно установить другой OTA через режим Recovery. Пока продолжается слияние снапшотов, избегайте любых действий, которые могут привести к бутлупу (например, установка модулей), поскольку в случае сбоя восстановить устройство получится только повторно разблокировав загрузчик, стирая все данные.

Узнать текущий статус процесса можно, выполнив команду: adb logcat -v color -s update_engine. Дополнительно, если установлено Custota (даже если оно не настроено на использование пользовательского OTA-сервера), приложение будет отображать соответствующее уведомление до завершения операции слияния снапшота.

Возврат на заводскую прошивку

Если вы хотите отказаться от использования avbroot и вернуться на стоковую прошивку:

1. Перезагрузитесь в р