What is this tutorial?
This tutorial will:
This tutorial will NOT:
Supported devices:
Current both the OnePlus 6 (enchilada) and 6t (fajita) have been tested, but newer phones should work as well.
For simplicities sake, all further references will only be to the 6t (fajita).
Pre-requisites:
Misc. notes:
*** WARNING ****
This process may brick your device. Do not proceed unless you are comfortable taking this risk.
*** WARNING ****
This process will delete all data on your phone! Do not proceed unless you have backed up your data!
*** WARNING ****
Make sure you have read through this entire process at least once before attempting, if you are uncomfortable with any steps include in this guide, do not continue.
And now on with the show!
Step 1: Basic setup
You need a few places to store things, so create some working directories:
You also need to add "~/android/lineageos/out/host/linux-x86/bin" to your shell's profile path. Make sure to close and restart your session afterwards otherwise the signing will fail later on with a "file not found" error message .
Step 2: Download the latest OxygenOS from OnePlus
Go to https://www.oneplus.com/support/softwareupgrade and download the latest OOS update, store it in ~/android/fajita/oos
Step 3: Extract the vendor.img from OOS
Run the following commands to extract the vendor.img from OOS:
You should now have a ~1g file named vendor.img in the images_raw directory.
Step 4: Update fajita's BoardConfig.mk
You will need to add a few parameters to the end of ~/android/lineageos/device/oneplus/fajita/BoardConfig.mk, they are:
Note you cannot use "~"" in the path names above to signify your home directory, so give the full absolute path to make sure the files are found.
Step 5: Update sdm845-common's BoardConfigCommon.mk (optional)
LineageOS by default disables Android Verified Boot's partition verification, but you can enable it now as all the required parts will be in place. However, you may not want to if you intend to make other changes to the system/boot/vendor partitions (like Magisk, etc.) after you have re-locked the bootloader.
To enable partition verification do the following:
Step 6: Patch the AOSP/LineageOS releasetools
Two releasetools included with LineageOS need to be patched as they otherwise will not properly process a pre-built vendor.img.
The required patches can be found here:
Download both and store in ~/android/fajita/patches.
Now apply them with the following commands:
Step 7: Build LineageOS
You are now ready to build:
Step 8: Prepare vendor.img
As part of the build process above, your raw vendor.img will been copied to the $OUT directory and a new hashtree (what AVB uses to verify the image) will have been added to it.
You need to use this new version in the signing process but due to how the build system works, this is not done by default.
So, let's put it where it is needed:
Step 9: Sign the APKs
You are now ready to sign the apks with sign_target_files_apks:
Note the new "--prebuilts_path" option, which points to where your new vendor.img file is located.
Step 10: Build the OTA
Now it is time to complete the OTA package:
Note, replace [date] with today's date in YYYYMMDD format.
Step 11: Create pkmd.bin for your phone
Before you can lock your phone, you have to tell it what your public key is so it knows it can trust your build.
To do this you need to create a pkmd.bin file:
Step 12: Flashing your LineageOS build
It's time to flash your build to your phone. The following steps assume you have already unlocked your phone and have flashed an official version of LineageOS to it. You don't need to have flashed LineageOS yet, you could use TWRP through "fastboot boot" if you prefer.
When the sideload is complete, reboot in to LineageOS. Make sure everything looks good with your build.
You may also need to format your data partition at this time depending on what you had installed on your phone previously.
Step 13: Flashing your signing key
Now it's time to add your signing key to the Android Verified Boot process. To do so, do the following:
Your phone will then factory reset and then reboot in to LineageOS.
Which of course means you have to go through the first time setup wizard, so do so now.
Step 14: Disable OEM unlock
Congratulations! Your boot loader is now locked, but you can still unlock it again using fastboot, so it's time to disable that as well.
Step 15: Profit!
Other things
So why can't I do this with official LineageOS builds?
For Android Verified Boot (AVB) to work, it must have the hash values for each of the system/vendor/boot/dtbo partitions stored in vbmeta. Official LineageOS builds do not include the vendor.img in them (for fajita at least, other phones may), instead simply using the existing partition on the phone.
That means that there is no vendor.img information in vbmeta for the official builds, which means AVB will fail to verify it during boot and give the red corruption message and halt the boot process after you have re-locked the bootloader.
And since you cannot add to vbmeta without the LineageOS private key, which only the LineageOS signing server has, you cannot add it.
This means you must do a full build with new signing keys to make it work.
Theoretically you could pick apart a LineageOS release, rehash the system/vendor/boot/dtbo and then recreate vbmeta and the payload.bin file, but that brings a host of other issues. For example, since such a "build" would look like a full LinageOS release, if you ever accidentally let the updater run it would brick (soft) that slot and you'd have swap back to your other slot to boot again. In an extreme case, if you managed to corrupt the second slot somehow you'd have to wipe your entire and recover from the brick with one of the available tools to do so.
Ok, what messages do I see during the boot process then?
During a boot you will of course see the standard OnePlus power up screen, followed by the yellow "custom os" message an then the stardard LineageOS boot animation.
For more details on AVB boot messages, see https://source.android.com/security/verifiedboot/boot-flow
So what do those two patches to the release tools do?
AOSP/LineageOS's add_image_to_target_files.py detects if a vendor.img file already exists, and if so, simply includes it in the build process. The patch adds one extra step, so that AVB is being enabled for the build, it will replace the existing hashtree on vendor.img using the same salt and other options as will be used on system/boot/dtbo. This ensure that when vbmeta is generated, it has the right information from vendor.img.
The script is called from the make system as part of the "mka target-files-package otatools" and the appropriate parameters from the make system, like "BOARD_PREBUILT_VENDORIMAGE", are used to create arguments to the script to build the standard image files as well as include the prebuilt vendor.img.
This script is used both during the initial build as well as the signing process, but this change is only targeted at the build time implementation. During signing, the script uses whatever hashtrees are in place and does not regenerate them.
AOSP/LineageOS's sign_target_files_apks.py is responsible for signing the APKs that have been built as part of "mka target-files-package otatools", unfortunately it is not part of the "make" system, so settings like "BOARD_PREBUILT_VENDORIMAGE" do not impact the script. This means that sign_target_files_apks.py does not have any knowledge that it should be including a pre-built vendor.img, even though it is in the $OUT directory waiting to be used.
The patch adds a new parameter to the script (--prebuilts_path), so that during the signing process, any image files found in the provided path, will be included in the process. So make sure that only vendor.img is in the provided directory. This is a directory instead of a single file as future uses may be to include things like firmware, other partition types, etc. in to the signing process.
Thank you's
This tutorial will:
- Creating an unofficial build of LineageOS 17.1 suitable for using to re-lock the bootloader on a OnePlus 6/6t
- Take you through the process of re-locking your bootloader after installing the above
This tutorial will NOT:
- Remove *all* warning messages during boot (the yellow "Custom OS" message will be present though the orange "Unlocked bootloader" message will not)
- Allow you to use official builds of LineageOS 17.1 on your device with a re-locked bootloader (more details near the end of the tutorial)
Supported devices:
Current both the OnePlus 6 (enchilada) and 6t (fajita) have been tested, but newer phones should work as well.
For simplicities sake, all further references will only be to the 6t (fajita).
Pre-requisites:
- a mid level knowledge of terminal commands and features
- a supported phone
- a PC with enough CPU/RAM to build LineageOS 17.1 (recommended 8 cores, 24g of RAM)
- a working USB cable
- fastboot/adb installed and functional
- LineageOS 17.1 source code downloaded
- at least one successful build of LineageOS
- at least one successful signing of your build with your own keys
Misc. notes:
- the basics of building/signing of LineageOS is outside the scope of this tutorial, refer to the LineageOS Wiki for details on how to complete these tasks
- you'll be modifying some code in LineageOS, so if you are not comfortable using basic editing utilities as well as patch, do not proceed any further
- the path to your LineageOS source code is going to be assumed to be ~/android/lineageos, if it is somewhere else, substitute the correct path in the tutorial
- the path to your private certificate files is going to be assumed to be ~/android-certs, if it is somewhere else, substitute the correct path in the tutorial
*** WARNING ****
This process may brick your device. Do not proceed unless you are comfortable taking this risk.
*** WARNING ****
This process will delete all data on your phone! Do not proceed unless you have backed up your data!
*** WARNING ****
Make sure you have read through this entire process at least once before attempting, if you are uncomfortable with any steps include in this guide, do not continue.
And now on with the show!
Step 1: Basic setup
You need a few places to store things, so create some working directories:
Code:
mkdir ~/android/fajita
mkdir ~/android/fajita/oos
mkdir ~/android/fajita/images
mkdir ~/android/fajita/images_raw
mkdir ~/android/fajita/patches
mkdir ~/android/fajita/pkmd
Step 2: Download the latest OxygenOS from OnePlus
Go to https://www.oneplus.com/support/softwareupgrade and download the latest OOS update, store it in ~/android/fajita/oos
Step 3: Extract the vendor.img from OOS
Run the following commands to extract the vendor.img from OOS:
Code:
cd ~/android/fajita/oos
unzip [oos file name you downloaded] payload.bin
cd ../images_raw
python ~/android/lineageos/lineage/scripts/update-payload-extractor/extract.py --partitions vendor --output_dir . ../oos/payload.bin
You should now have a ~1g file named vendor.img in the images_raw directory.
Step 4: Update fajita's BoardConfig.mk
You will need to add a few parameters to the end of ~/android/lineageos/device/oneplus/fajita/BoardConfig.mk, they are:
Code:
BOARD_PREBUILT_VENDORIMAGE := /home/<userid>/android/fajita/images_raw/vendor.img
AB_OTA_PARTITIONS += vendor
BOARD_AVB_ALGORITHM := SHA256_RSA2048
BOARD_AVB_KEY_PATH := /home/<userid>/.android-certs/releasekey.key
Note you cannot use "~"" in the path names above to signify your home directory, so give the full absolute path to make sure the files are found.
Step 5: Update sdm845-common's BoardConfigCommon.mk (optional)
LineageOS by default disables Android Verified Boot's partition verification, but you can enable it now as all the required parts will be in place. However, you may not want to if you intend to make other changes to the system/boot/vendor partitions (like Magisk, etc.) after you have re-locked the bootloader.
To enable partition verification do the following:
Code:
cd ~/android/lineageos/devices/sdm845-common
sed -i 's/^BOARD_AVB_MAKE_VBMETA_IMAGE_ARGS += --flag 2/#BOARD_AVB_MAKE_VBMETA_IMAGE_ARGS += --flag 2/' BoardConfigCommon.mk
Step 6: Patch the AOSP/LineageOS releasetools
Two releasetools included with LineageOS need to be patched as they otherwise will not properly process a pre-built vendor.img.
The required patches can be found here:
- https://raw.githubusercontent.com/W.../source/add_img_to_target_files.py-17.1.patch
- https://raw.githubusercontent.com/W...r/source/sign_target_files_apks.py-17.1.patch
Download both and store in ~/android/fajita/patches.
Now apply them with the following commands:
Code:
cd ~/android/lineageos/build/tools/releasetools
patch add_image_to_target_files.py ~/android/fajita/patches/add_image_to_target_files.py-17.1.patch
patch sign_target_files_apks.py ~/android/fajita/patches/sign_target_files_apks.py-17.1.patch
Step 7: Build LineageOS
You are now ready to build:
Code:
cd ~/android/lineageos
source build/envsetup.sh
croot
breakfast fajita
mka target-files-package otatools
Step 8: Prepare vendor.img
As part of the build process above, your raw vendor.img will been copied to the $OUT directory and a new hashtree (what AVB uses to verify the image) will have been added to it.
You need to use this new version in the signing process but due to how the build system works, this is not done by default.
So, let's put it where it is needed:
Code:
cp $OUT/obj/PACKAGING/target_files_intermediates/lineage_fajita-target_files-eng.*/IMAGES/vendor.img ~/android/fajita/images
Step 9: Sign the APKs
You are now ready to sign the apks with sign_target_files_apks:
Code:
./build/tools/releasetools/sign_target_files_apks -o -d ~/.android-certs --prebuilts_path ~/android/fajita/images $OUT/obj/PACKAGING/target_files_intermediates/*-target_files-*.zip signed-target_files.zip
Note the new "--prebuilts_path" option, which points to where your new vendor.img file is located.
Step 10: Build the OTA
Now it is time to complete the OTA package:
Code:
./build/tools/releasetools/ota_from_target_files -k ~/.android-certs/releasekey --block signed-target_files.zip lineage-17.1-[date]-UNOFFICIAL-fajita-signed.zip
Note, replace [date] with today's date in YYYYMMDD format.
Step 11: Create pkmd.bin for your phone
Before you can lock your phone, you have to tell it what your public key is so it knows it can trust your build.
To do this you need to create a pkmd.bin file:
Code:
~/android/lineageos/external/avb/avbtool extract_public_key --key ~/.android-certs/releasekey.key --output ~/android/fajita/pkmd/pkmd.bin
Step 12: Flashing your LineageOS build
It's time to flash your build to your phone. The following steps assume you have already unlocked your phone and have flashed an official version of LineageOS to it. You don't need to have flashed LineageOS yet, you could use TWRP through "fastboot boot" if you prefer.
- Reboot your phone in to recovery mode
- In LineageOS Recovery select "Apply update"
- From your PC, run:
Code:
adb sideload ~/android/lineageos/lineage-17.1-[date]-UNOFFICIAL-fajita-signed.zip
You may also need to format your data partition at this time depending on what you had installed on your phone previously.
Step 13: Flashing your signing key
Now it's time to add your signing key to the Android Verified Boot process. To do so, do the following:
- Reboot your phone in to fastboot mode
- From your PC, run:
Code:
fastboot flash avb_custom_key ~/android/fajita/pkmd/pkmd.bin
fastboot reboot bootloader
fastboot oem lock
- On your phone, confirm you want to re-lock and it will reboot
Your phone will then factory reset and then reboot in to LineageOS.
Which of course means you have to go through the first time setup wizard, so do so now.
Step 14: Disable OEM unlock
Congratulations! Your boot loader is now locked, but you can still unlock it again using fastboot, so it's time to disable that as well.
- Unlock you phone and go to Settings->About phone
- Scroll to the bottom and find "Build number"
- Tap on it you enable the developer options
- Go to Settings->System->Advanced->Developer options
- Disable the "OEM unlocking" slider
- Reboot
Step 15: Profit!
Other things
- The above will build a standard USERDEBUG version of LineageOS, however this will still allow LineageOS Recovery to sideload non-signed files. If you have implemented step 5 above, then this protects your system/vendor/boot/dtbo partitions, but none of the others. Likewise USERDEBUG builds will allow for rolling back to a previous version. To increase security and disallow both of these scenarios you may want to build a USER version of LineageOS to install. However this brings in other issues, such as flashing newer firmware from OnePlus so make sure you understand the implications of both choices. For more details on build types, see https://source.android.com/setup/develop/new-device#build-variants.
- In the above example the releasekey from your LineageOS install has been used to sign AVB, but AVB supports other key strengths up to SHA512_RSA8192. You could create a key just for signing AVB that used different options than the default keys generated to sign LineageOS.
- If you want to remove you signing key from your phone, you can do it by running "fastboot erase avb_custom_key".
- The changes you made to the make files and releasetools may conflict with future updates that you pull from LineageOS through repo sync, if you have to reset the files to get repo sync to complete successfully, you'll have to reapply the changes afterwards.
So why can't I do this with official LineageOS builds?
For Android Verified Boot (AVB) to work, it must have the hash values for each of the system/vendor/boot/dtbo partitions stored in vbmeta. Official LineageOS builds do not include the vendor.img in them (for fajita at least, other phones may), instead simply using the existing partition on the phone.
That means that there is no vendor.img information in vbmeta for the official builds, which means AVB will fail to verify it during boot and give the red corruption message and halt the boot process after you have re-locked the bootloader.
And since you cannot add to vbmeta without the LineageOS private key, which only the LineageOS signing server has, you cannot add it.
This means you must do a full build with new signing keys to make it work.
Theoretically you could pick apart a LineageOS release, rehash the system/vendor/boot/dtbo and then recreate vbmeta and the payload.bin file, but that brings a host of other issues. For example, since such a "build" would look like a full LinageOS release, if you ever accidentally let the updater run it would brick (soft) that slot and you'd have swap back to your other slot to boot again. In an extreme case, if you managed to corrupt the second slot somehow you'd have to wipe your entire and recover from the brick with one of the available tools to do so.
Ok, what messages do I see during the boot process then?
During a boot you will of course see the standard OnePlus power up screen, followed by the yellow "custom os" message an then the stardard LineageOS boot animation.
For more details on AVB boot messages, see https://source.android.com/security/verifiedboot/boot-flow
So what do those two patches to the release tools do?
AOSP/LineageOS's add_image_to_target_files.py detects if a vendor.img file already exists, and if so, simply includes it in the build process. The patch adds one extra step, so that AVB is being enabled for the build, it will replace the existing hashtree on vendor.img using the same salt and other options as will be used on system/boot/dtbo. This ensure that when vbmeta is generated, it has the right information from vendor.img.
The script is called from the make system as part of the "mka target-files-package otatools" and the appropriate parameters from the make system, like "BOARD_PREBUILT_VENDORIMAGE", are used to create arguments to the script to build the standard image files as well as include the prebuilt vendor.img.
This script is used both during the initial build as well as the signing process, but this change is only targeted at the build time implementation. During signing, the script uses whatever hashtrees are in place and does not regenerate them.
AOSP/LineageOS's sign_target_files_apks.py is responsible for signing the APKs that have been built as part of "mka target-files-package otatools", unfortunately it is not part of the "make" system, so settings like "BOARD_PREBUILT_VENDORIMAGE" do not impact the script. This means that sign_target_files_apks.py does not have any knowledge that it should be including a pre-built vendor.img, even though it is in the $OUT directory waiting to be used.
The patch adds a new parameter to the script (--prebuilts_path), so that during the signing process, any image files found in the provided path, will be included in the process. So make sure that only vendor.img is in the provided directory. This is a directory instead of a single file as future uses may be to include things like firmware, other partition types, etc. in to the signing process.
Thank you's
- Obviously to all of the members of the LineageOS team!
- LuK1337 for supporting fajita
- optimumpro for the OnePlus 5/5t re-locking guide (https://forum.xda-developers.com/oneplus-5/how-to/guide-relock-bootloader-custom-rom-t3849299) which inspired this one
- Quark.23 for helping with the process and testing on enchilada
Last edited: