Table of Contents:
The current implementation is a technology preview and it is expected to stabilize during the release cycles leading to the v2022 stable release. The prototype is already available in Apertis as documented here, but it may be subject to potentially incompatible changes during the upstream review process.
This signature system relies on OSTree’s library functions. Therefore, the key generation and storage process is identical to what is described in the System updates and rollback design document.
Flatpak application signatures occur on several levels:
- single commits
- whole repositories
- single-file bundles
Please note, however, that GPG signatures are disabled on Apertis. It is still possible to pull from GPG-signed repositories, but those signatures won’t be verified. Similarly, it is not possible to sign flatpak applications using GPG.
Creating signed flatpak applications
The simplest way to create a signed flatpak is to use
--sign=<SECRETKEY> command-line argument, where
<SECRETKEY> is the
base64-encoded secret Ed25519 key. This ensures the OSTree commit and summary
are properly signed:
flatpak-builder --repo=myrepo --sign=m8/rp9I9ax2w81yujZyeXTfZlbeBjEBUPQSQKo14iHgHdrzpKYH6xvL83midrFNeMrU4QBtk4jZ+x2veQoP4oQ== build-dir org.example.sampleapplication.yaml
For more advanced usage, the same command-line option can also be used with the following flatpak commands:
These commands allow one to create Ed25519-signed commits from an unsigned repository or bundle, or to create signed bundles as explained below.
Multiple occurrences of the
--sign option are allowed in to order to permit
multiple signatures of each object.
More details about those commands are available in the Flatpak documentation.
Publishing signed flatpaks applications
Publishing a repository
When distributing several applications, it can be useful to publish the whole repository using a .flatpakrepo file.
The only difference here is that the
GPGKey=... line must be replaced with
<PUBLICKEY> is the base64-encoded public
Such a .flatpakrepo file could be:
[Flatpak Repo] Title=Sample Repository Url=https://example.org/flatpak/repo Homepage=https://example.org/flatpak Comment=Sample Flatpak repository signed with Ed25519 Description=This Flatpak repository provides applications signed with Ed25519 Icon=https://example.org/flatpak/icon.svg SignatureKey=B3a86SmB+sby/N5onaxTXjK1OEAbZOI2fsdr3kKD+KE=
Publishing a single application
One convenient way to distribute single flatpak applications is to use .flatpakref files. Those files include all necessary information for flatpak to be able to install and update the application.
Exactly as it is done with with
.flatpakrepo files, using
SignatureKey=<PUBLICKEY> instead of
GPGKey=... will instruct flatpak to
enable Ed25519 signature verification for this repository.
This line will instruct flatpak to add the corresponding configuration keys to the remote and perform signature verification when installing and/or updating this application.
Such a .flatpakref file could be:
[Flatpak Ref] Name=org.example.sampleapplication Title=Sample application from our example repo Url=https://example.org/flatpak/repo RuntimeRepo=https://example.org/flatpak/example.flatpakrepo IsRuntime=false SignatureKey=B3a86SmB+sby/N5onaxTXjK1OEAbZOI2fsdr3kKD+KE=
Publishing a bundle
Flatpak applications can also be distributed as
which can be created using the
flatpak build-bundle command. As previously
mentioned, these bundles can be signed by adding the
to the command invocation:
flatpak build-bundle --sign=m8/rp9I9ax2w81yujZyeXTfZlbeBjEBUPQSQKo14iHgHdrzpKYH6xvL83midrFNeMrU4QBtk4jZ+x2veQoP4oQ== myrepo example.bundle org.example.sampleapplication
However, when publishing a signed flatpak bundle, the corresponding public key has to be stored in a location easily accessible to the final user for signature verification, as the bundle file itself is signed and doesn’t provide any mean to retrieve the associated public key.
Installing a signed flatpak
Configuring a remote repository
If the repository publisher provides a
.flatpakrepo file including the public key,
then no action is needed other than running
flatpak remote-add <REPONAME> <REPOFILE>.
However, if such a file is not available, one must add the
command-line option to the
flatpak remote-add command in order to provide
either the public key directly, or a file containing the public key:
--sign-verify=ed25519=inline:<PUBLICKEY>is used to directly specify the public key needed to verify this repository
--sign-verify=ed25519=file:<PATH>can be used to point flatpak to a file containing a list of public keys (base64-encoded, one key per line), among which at least one can be used to verify signatures for this repository
flatpak remote-add example example.flatpakrepo
flatpak remote-add --sign-verify=ed25519=inline:B3a86SmB+sby/N5onaxTXjK1OEAbZOI2fsdr3kKD+KE= example https://example.org/flatpak/repo
--sign-verify occurrences are allowed in order to specify as many
public keys as needed. This can be useful when a new signature key is being
deployed, while the old one is still in use: by specifying both the old and the
new key, users can make sure at least one of those will be able to verify the
signatures. That way, once the old key is revoked and only the new one is used
for signing the repository, the corresponding remote will keep working as
This option can also be added when using the
flatpak remote-modify command.
Installing a signed application
Similarly to the process of using
.flatpakrepo files, when installing a single
application using a
.flatpakref file including the public key, no additional
action is needed. Flatpak will automatically verify Ed25519 signatures using the
provided public key:
flatpak install --from example.flatpakref
When the application is installed from a previously configured repository, signature verification is also automated, as long as the corresponding public key has been imported into the remote’s configuration:
flatpak install org.example.sampleapplication
If the public key has not been previously imported into the remote’s
configuration, one can also use the
--sign-verify command-line option:
flatpak install --sign-verify=ed25519=inline:B3a86SmB+sby/N5onaxTXjK1OEAbZOI2fsdr3kKD+KE= org.example.sampleapplication
Installing a signed bundle
Flatpak bundles are not installed from a repository like most flatpak
applications, but from a single, optionally signed, file. As there is no
repository configuration to import public keys from, the user needs to specify
the relevant public keys using the
--sign-verify command-line option as stated
flatpak install --sign-verify=ed25519=inline:B3a86SmB+sby/N5onaxTXjK1OEAbZOI2fsdr3kKD+KE= --bundle example.bundle
This option works the same way with both
flatpak build-import-bundle and
flatpak install commands.
Flatpak reference documentation: https://docs.flatpak.org/