Skip to main content

Signing: F-Droid Repo

This guide explains how to sign a custom F-Droid repository with signing keys that are stored in a security key or a Hardware Security Module (HSM).

Prerequisites​

Generate a key pair​

You need to generate a signing key pair and certificate. These objects need to be ready on your hardware token before you start with your F-Droid repo. Follow this guide and generate a signing key pair with label myproject-fdroid-repo.

Background: This is needed because even though fdroidserver can automatically generate a key pair, this is done using Java's keytool, which is not compatible with the Nitrokey HSM.

Install dependencies​

First install fdroidserver. On Debian-based systems:

sudo apt install --no-install-recommends fdroidserver

However, due to a bug in apksigner with recent versions of Java, you actually need to use install a patched version of fdroidserver. We only did the previous step to ensure that all of the dependencies are present and installed via apt.

sudo apt install --no-install-recommends python3-venv
python3 -m venv venv
source venv/bin/activate
pip3 install git+https://gitlab.com/thgoebel/fdroidserver.git@fix-apksigner-reflection

Until this patch is merged and has made its way into fdroidserver in apt, you will need to run fdroidserver as follows:

source venv/bin/activate
fdroid --help

Initialize a new repository​

mkdir fdroid
cd fdroid
fdroid init --keystore NONE

You can ignore the warning about the missing Android SDK, because you won't be compiling Android apps with fdroidserver.

Configuration​

Edit the config.yml that is generated. Set the values as you desire, in particular the repo name and description.

For the signing, define the following fields:

repo_keyalias: myproject-fdroid-repo

keystore: "NONE"
keystorepass: { env: USER_PIN }

Set the User PIN of your hardware token as an environment variable:

export USER_PIN=12345678

Add a new app​

Copy a signed APK file (*.apk) and the v4 signature file (*.idsig) to the repo/ directory. (The *.idsig files are currently not used by F-Droid. But collecting them anyway does not hurt.)

Next, update the index:

fdroid update --create-metadata

The --create-metadata option is only needed when adding a completely new app. It will create some skeleton files in metadata/. Fill these out according to your needs. Not all fields will be necessary -- see the Metadata Reference.

Then re-run the command to re-create the index with the new metadata:

fdroid update
info

If you are not using the patched fdroidserver (see above), you will run into the error described in this ticket.

Update an existing app​

  1. Copy the *.apk and *.idsig to repo/
  2. Update the CurrentVersionCode field in the metadata/app.yml. This is the version that will be suggested to users.
  3. export USER_PIN=12345678
  4. fdroid update

Publish the repository​

Deploy the repo/ directory to a public webserver, such as https://packages.fmd-foss.org/fdroid/repo. As a convention, the URL should end in fdroid/repo/.

References​