Signing Applications

In order to publish applications so that users can install them in a reliable and secure way, you need to sign the flatpaks that you create using a GPG key. It can also be useful to enable GPG verification when working with local repositories to ensure that flatpak signing is working correctly.

When generating a key, you are actually generating a keypair – a private key and a public key.

Creating a Signing Key

If you do not already have a key for signing flatpaks then you need to generate one using GPG, either on the command line or using one of its graphical front-ends. There are many ways to generate a new key with gpg on the command line. For simplicity, we give three ways to perform this task.

A user-friendly way to create a key is to use the --generate-key option. GPG will ask you to answer some simple questions and use sensible defaults to generate a key:

gpg --generate-key

A more detailed version of the above option is --full-generate-key which lets you fine-tune some of the details:

gpg --full-generate-key

If you already know the answers to the questions that GPG will ask when either of the above two options are used, you can use the --quick-generate-key option with a sequence of arguments that provide the answers.

For example, we can quickly generate a new key with a user ID, algorithm, usage and expiration date:

gpg --quick-generate-key 'User Name (Signing key) <user@name.invalid>' rsa3072 default 1y

If using this method you should use appropriate values for these arguments.

Signing the Application

When developing an application it is probably not necessary to sign each flatpak that you produce. However, when building a flatpak for distribution, you must sign it with the GPG key that you generated for the purpose. The syntax for this is as follows:

flatpak-builder --repo=<repo> --gpg-sign=<key ID> --force-clean <build dir> <application ID>

For example, in the following command we rebuild an application with the ID com.example.my_application and sign it with a key whose ID begins with 3043E8F5:

flatpak-builder --repo=myrepo --gpg-sign=3043E8F5 --force-clean _flatpak com.example.my_application.json

You should specify the full key ID instead of just the first 8 characters. We have truncated the ID for clarity.

The application should now be available in the myrepo repository.

Adding a Signed Repository

The myrepo repository will need to be added to the system before the signed application can be installed. This is done in a similar way to that described in Installing from a Local Repository. However, where that section used the --no-gpg-verify option to skip signing checks, we now need to manage the public key used to verify signatures.

We can export the public key from a keyring and use it to register the repository with flatpak in two steps, using the key:

gpg --export -a <key ID> > key.asc
flatpak --user remote-add --gpg-import=key.pub my-app-repo myrepo

This adds the my-app-repo remote, referring to the repository in the myrepo directory.

Alternatively, if you want to avoid using files, it can also be done in a single step, again using the key ID from earlier, truncated for clarity:

gpg --export -a 3043E8F5 | flatpak --user remote-add --gpg-import=- my-app-repo myrepo

The application can then be installed in the usual way:

flatpak install my-app-repo com.example.my_application

The repository can be managed using the commands given in Installing from a Local Repository.