1# How ADB incremental-install works 2 3The regular way an app is installed on an Android devices is for ADB to open a 4connection to the package manager (`pm`) and write all the bytes. Once received 5by `pm`, the app is verified via v2 signature checking, adb gets an 6installation reply (SUCCESS or FAILURE [..]), and the operation is considered 7over. 8 9Incremental-install is a departure from the idea that all bytes needs to be 10pushed for the installation to be considered over. It even allows an app to 11start before `pm` has received all the bytes. 12 13## The big picture 14 15The big picture of incremental-install revolves around four concepts. 16 17- Blocks 18- Block requests 19- Incremental Server (`IS`) 20- V4 signature 21 22Each file of an app (apk, splits, obb) are viewed as a series of blocks. 23 24In incremental-install mode, `pm` only need to receive a few blocks to validate 25the app and declare installation over (with SUCCESS/FAILURE) which increase 26installation speed tremendously. 27 28In the background, ADB will keep on steaming blocks linearly, even after `pm` 29reported being "done". The background streaming is done in ADB's embedded 30`IS`. 31 32The `IS` sends blocks to the device in order it assumes will be accessed by `pm`. 33And then it sends the remaining block from start to end of file. 34 35`pm` will inevitably need blocks it has not received yet. For example, when the 36app's Central Directory (located at the end of a zip file) must be read to know 37what files are in the apk. This is where block requests enter the picture. The 38Android device can issue requests which will make the `IS` bump the priority of 39a block so it is sent to the device as soon as possible. 40 41### Incremental-install filesystem 42 43The block requests are not issued by Android Frameworks. Framework is completely 44oblivious of the background streaming. Everything is done at the Android kernel 45level where file access is detected. If a read lands on a block that has not been 46received yet, the kernel issues a block request to get it from the streaming 47server immediately. 48 49### App verification 50 51In incremental-install mode, `pm` does minimal verification of app integrity. 52- Checks that there is a v4 signature 53- Check there is a v2 or v3 signature 54- Check that v4 is linked to either v2 or v3 55- Check the v4 header is signed with same certificate as v2/v3 56 57The rest of the app verification is done by the Android kernel for each block level 58when they are received. 59 60With v2 signing, an apps is signed by building a merkle tree, keeping only the 61top node hash, signing it, and embedding it in the apk. On `pm` side, to verify 62the app, the merkle tree is rebuilt, and the top hash is compared against the 63signed hash. V2 can only work if `pm` has all the bytes of an app which is not 64the case here. 65 66#### v4 signing 67This problem is solved with V4 signing which does not discard the merkle tree 68but embed it in the signed file and also outputs the top merkle node hash in 69a .idsig file. 70 71Upon installation the whole merkel tree from V4 is given to `pm` which forwards 72it to the Android kernel. The kernel is in charge of verifying the integrity 73of each block when they are received from the `IS` via the merkle tree. 74 75For more details about v4 signing, refer to [APK signature scheme v4](https://source.android.com/docs/security/features/apksigning/v4) page. 76## How ADB performs incremental-install 77 78To perform incremental-install, ADB needs to do two things. 79 80- Define the block database to `pm`. 81- Start a `IS`. 82 83``` 84 ┌───┐ ┌────┐ 85 │adb│ │ppm │ 86 └─┬─┘ └─┬──┘ 87 │ pm install-incremental │ 88 ├─────────────────────────────────►│ 89 │ ┌────┐ │ 90 ├───►│ IS │ │ 91 │ └─┬──┘ │ 92 X │ │ 93 ├──────────────────────────►│ 94 ├──────────────────────────►│ 95 │◄──────────────────────────┤ 96 ├──────────────────────────►│ 97 │ │ 98``` 99 100### Local database 101 102The call to `pm incremental-install` has arguments describing the `IS` database. 103It allows the kernel to issue block requests. The arg format to describe the `IS` 104database is as follows. 105 106``` 107filename:file_size:file_id:signature[:protocol_version] 108``` 109 110where 111 112- `file_id` is the identified that will be used by the kernel for block 113requests. There is one arg for each file to be streamed. 114- `signature` is the top merkle hash. 115- `[:protocol_version]` is optional. 116 117### Unsigned files 118 119There could be unsigned files to be installed. In this case, `pm` has to be made 120aware of them via a special arg format. 121 122``` 123filename::file_size:file_id 124``` 125 126These files are not sent via the `IS` but instead sent on stdin, before 127the `IS` is started. 128 129``` 130 ┌───┐ ┌────┐ 131 │adb│ │ppm │ 132 └─┬─┘ └─┬──┘ 133 │ pm install-incremental │ 134 ├─────────────────────────────────►│ 135 │ │ 136 │ (stdin) write(unsigned) │ 137 ├─────────────────────────────────►│ 138 │ ┌────┐ │ 139 ├───►│ IS │ │ 140 │ └─┬──┘ │ 141 X │ │ 142 ├──────────────────────────►│ 143 ├──────────────────────────►│ 144 │◄──────────────────────────┤ 145 ├──────────────────────────►│ 146 │ │ 147``` 148 149## Learn more 150 151There is more documentation about this topic which is unfortunately internal only. 152 153- [go/incremental-adb](go/incremental-adb) 154- [go/apk-v4-signature-format](go/apk-v4-signature-format) 155- [go/instamatic-design-signature](go/instamatic-design-signature)