Verifying Envoy on Android
One of the core tenets we live by here at Foundation is that of “don’t trust, verify.” We’ve long had a detailed guide available for verifying and updating the firmware on Passport in a secure way, but we want to expand on that by empowering users to more easily validate Envoy on Android. In this guide we’ll walk through the “why” and “how” of verifying the APK file (the raw binaries that Android uses for manually installing applications) with both simple hash verification and full PGP signature validation to ensure that the app you install is exactly what we published and has not been tampered with in any way.
Why is verification important?
While the Google Play Store and Apple App Store provide a secure centralized method to distribute apps, control over the published application ends up in the hands of Google and Apple, respectively. Because of these centralized “walled gardens,” the ability for end users to verify that the applications they are installing are exactly what the developers publish is minimized, and trust is placed in the app store provider.
When downloading the APK directly from Github, however, we unlock the ability to provide additional guarantees that the application you’re installing is exactly what we at Foundation have made and that it has not been tampered with along the way. Because we’re focused on securely storing and spending Bitcoin with Passport and Envoy, many users understandably want to take as many steps as possible to ensure that their funds are safe against even advanced attacks.
When downloading binaries directly (essentially what an APK file is), even from websites you’d normally trust like Github, you’re placing trust in the source of that binary to match the source code you expect. Verifying the zipped (or compressed) APK file we publish on Github prevents Github (or a malicious attacker somehow injecting themselves between you and Github’s servers!) from being able to tamper with the Envoy APK without being detected. This verification process does require some extra work but can provide additional peace of mind to users of Envoy while reducing trust in third-parties.
Let’s look at how exactly we can perform this verification on Android itself.
Simple hash verification
While full verification via PGP keys is more secure, simple hash verification is very easy and faster to perform while still giving some security guarantees against more trivial man-in-the-middle attacks. A hash of a file is a fixed-length string that uniquely represents a given file, where changing even a single bit of the file would result in an entirely different hash. As a given input file can only have a single hash, comparing the expected hash against the downloaded file ensures that not even a single bit in the file has been changed or corrupted.
- Download and install “DeadHash” via the Google Play Store or F-Droid
- Copy the SHA-256 hash for the Envoy APK zip file from the Github release page
- The hash will look something like this:
- This SHA-256 hash (the same hashing algorithm used for Bitcoin mining!) is a way to represent the file in a way that cannot be falsified
- Open DeadHash and select the folder icon to choose the Envoy APK zip file
- Select the downloaded APK zip file, i.e.
- Select the downloaded APK zip file, i.e.
- Paste the hash you copied into the “Compare” field
- Press “Calculate”
- Ensure that the SHA-256 hash validates and gives you a nice green check-mark
- All of the hashing algorithms except for SHA-256 should show a red X, as we’ve only provided the SHA-256 hash
- If you get a red X for all hashes, including SHA-256, stop immediately and reach out to us at firstname.lastname@example.org! If it does match, you’re all set.
Fully verifying Envoy via PGP
While more involved than simple hash verification, taking the time to validate our PGP key and signatures ensures that as many threats as possible are mitigated. When you validate the PGP keys and signatures of Envoy, you ensure that only a successful attack would require both the PGP private keys and control over our Github account(s). This verification also entirely mitigates the risk, however minor, of Github themselves tampering with the APK.
Before we get started, you’ll need to download and install a separate app on your Android device to enable you to validate the PGP key used to sign the Envoy zip file, and then import the Envoy signing key. For each of the steps below with commands (i.e.
pkg install wget gnupg -y), simply copy and paste these into Termux and hit enter.
- Install the Termux app from Github or F-Droid
- Open Termux and install the required packages
pkg install wget gnupg -y
- Download the Envoy signing PGP key
- Download the Envoy APK file, manifest file, and PGP signature file
- Replace the links below with those from the latest release!
- Import the Envoy signing PGP key
gpg --import envoy_key.pgp
- Validate the key ID that is shown on the first or second line matches that on https://foundationdevices.com/pgp/ under “Envoy Signing Key”
- i.e. “E8CE0DD2B5528043” (note that the key is not case sensitive)
- If the key does NOT match, stop immediately and reach out to us at email@example.com! If it does match, proceed to step two below
- This step imports the PGP key we publish on our website, allowing you to properly validate our PGP signature in the next step
- Verify the “envoy-manifest.txt” file is properly signed with our Envoy signing PGP key
gpg --verify envoy-manifest.txt.asc envoy-manifest.txt
- You should see output including “Good signature from ‘Igor Cota <firstname.lastname@example.org>‘” in a line of the output from this step
- This step ensures that the GPG key we publish was the one used to sign the envoy-manifest.txt file, and that the file has not been tampered with in any way
- Verify the Envoy APK zip file
echo "$(grep "envoy-apk" envoy-manifest.txt)" | sha256sum --check
- This step compares the hash for the APK zip in the envoy-manifest.txt file that we’ve verified via PGP with the SHA-256 hash of the actual APK zip file we’ve downloaded, ensuring no tampering or corruption has happened
- If the output says something like
envoy-apk-1.0.7-18.zip: OK, you’ve successfully verified the binary and can go ahead and install with added peace of mind
- Note that the file name will change with each release, but you should always get the “OK” at the end!
- If the output does NOT say “OK“, stop immediately and reach out to us at email@example.com!
Congratulations on successfully verifying Envoy! These steps are certainly going above and beyond, but keeping with the “don’t trust, verify” mantra is one that always pays off. If you’d like to read more about the PGP or simple hash verification process, you can take a look at the following links: