The CommonsBlog


Android Studio and distributionSha256Sum

It is common, though perhaps not widespread, to be given a checksum or hash when you go to download something. For example, when you go to download a Google Pixel image for Android P, you are given SHA-256 checksums for the ZIP files. That way, you can confirm that the ZIP file was downloaded correctly. Back in the early days of the Internet, checksums were good for confirming that some bits didn’t get flipped by accident in your download.

(if you’re under 40, ask your parents about “dial-up Internet”)

Nowadays, though, the concern is security. Having a separate checksum makes it a bit more difficult for an attacker to substitute a hacked file for the real one that you are trying to download.

Gradle offers support for this as part of the Gradle Wrapper. In addition to having a distributionUrl line in gradle-wrapper.properties, you can have a distributionSha256Sum line with a SHA-256 checksum for the Gradle ZIP listed in the distributionUrl. So, for example, if you have:

distributionUrl=https\://services.gradle.org/distributions/gradle-4.4-all.zip

you can also have:

distributionSha256Sum=7a2c66d1a78f811d5f37d14630ad21cec5e77a2a4dc61e787e2257a6341016ce

You have to get the SHA-256 checksum value yourself, from the server that has the ZIP files. When the Gradle tooling API, gradlew, or gradlew.bat need to download Gradle, they will check the SHA-256 hash of the downloaded ZIP file against the supplied distributionSha256Sum. If there is a mismatch, that ZIP will not be unpacked.

Ideally, we would have distributionSha256Sum values in all of our gradle-wrapper.properties files. Instead, few do, for (at least) two reasons.

First, the process is very manual. Android Studio could add the appropriate value when it creates or modifies the gradle-wrapper.properties file. It doesn’t, though, so developers need to go get these values themselves, or hope that somebody gives them a tool that simplifies it a bit.

Second, if there is a mismatch between the SHA-256 checksum and the actual ZIP file hash… Android Studio crashes hard, without even an error dialog. Android Studio needs a better UX here. That in turn might require fixes to the Gradle tooling API to provide more options for handling this situation, though it has been a couple of years since I filed the issue to try to stop Android Studio from crashing here.

Long-term, with some amount of luck, these things will get addressed. I look forward to someday having distributionSha256Sum in more Android projects.


Do you need a book on Android app development, but are having trouble finding one that is new enough? Try The Busy Coder’s Guide to Android Development!