AutoFirma AppImage

A portable, community-maintained Linux package of the Spanish Government's AutoFirma electronic-signature client.

Important

This project is not affiliated with or endorsed by the Spanish Government. It provides community packaging for the upstream AutoFirma application.

Highlights

• One self-contained x86_64 AppImage
• Bundled, reduced Java 17 runtime
• No installation or root access required
• Automatic first-run certificate generation
• PC/SC support for smart cards and DNIe
• Docker-only build and integration-test environment
• Pinned upstream source, build images, and downloaded artifacts

The package intentionally does not modify desktop settings or browser trust stores. Protocol registration and certificate trust remain under the user's control.

Install

Download the AppImage and its adjacent .sha256 file from the latest release, then verify and run it:

sha256sum --check AutoFirma-1.9.2-x86_64.AppImage.sha256
chmod +x AutoFirma-1.9.2-x86_64.AppImage
./AutoFirma-1.9.2-x86_64.AppImage

No files need to be installed system-wide. Keep the AppImage at a stable path if a desktop integration tool uses it to handle afirma:// links.

First launch

AutoFirma creates its local certificate pair in:

~/.afirma/Autofirma/
├── Autofirma_ROOT.cer
└── autofirma.pfx

If either file is missing, the next launch regenerates the pair. A setup failure produces a warning but does not prevent the desktop application from opening.

Browser signing

Signing from a browser requires both protocol registration and certificate trust.

1. Register the afirma:// protocol

The embedded desktop entry declares x-scheme-handler/afirma. An AppImage integration tool can install that entry and its icon automatically.

Without such a tool, create a user desktop entry that launches the AppImage from its permanent location and declares the same MIME handler. The AppImage does not register or remove handlers itself.

2. Trust the local certificate authority

Import the following file as a certificate authority trusted to identify websites:

~/.afirma/Autofirma/Autofirma_ROOT.cer

Browser	Certificate settings
Firefox	Settings → Privacy & Security → Certificates → View Certificates → Authorities → Import
Chromium-based browsers	Open the browser's certificate manager and import it under Authorities

Note

Browsers installed through Flatpak or Snap may use a confined profile. The certificate must be imported from a location visible inside that sandbox.

Smart cards and DNIe

The AppImage bundles the PC/SC client library required by Java. The host still needs a running pcscd service and the driver for the connected card reader.

On Debian and Ubuntu, the common packages are:

sudo apt install pcscd libccid
sudo systemctl enable --now pcscd

Package and service names vary between distributions.

Build from source

Requirements:

• Docker with Buildx support
• GNU Make

Build the AppImage and run the complete test suite:

make

Artifacts are written to out/:

out/
├── AutoFirma-1.9.2-x86_64.AppImage
└── AutoFirma-1.9.2-x86_64.AppImage.sha256

All compilation, packaging, linting, and integration testing runs in containers. The host does not need Java, Maven, or ShellCheck.

Make targets

Target	Description
make	Build the AppImage, lint the shell code, and run all tests
make appimage	Build the AppImage without running tests
make test	Run ShellCheck, build the tester image, and execute integration tests
make shellcheck	Lint all POSIX shell files with pinned ShellCheck 0.11.0
make shell	Open the assembler stage for debugging
make clean	Remove generated artifacts from out/
make help	List the available targets

Build configuration

Override a default with make VARIABLE=value:

Variable	Default	Purpose
AUTOFIRMA_VERSION	1.9.2	Upstream tag and artifact version
AUTOFIRMA_COMMIT	b4fe147c32…	Commit to which the upstream tag must resolve
JWS_COMMIT	8c5766a293…	Java-WebSocket revision used for the upstream issue 320 workaround
APPIMAGE_BUILD	1	Packaging revision used in release tags

AUTOFIRMA_VERSION and AUTOFIRMA_COMMIT must be updated together. The build fetches the configured tag and rejects it if it does not resolve to the configured commit.

GitHub Actions persists intermediate BuildKit layers between workflow runs. Local builds use the selected builder's normal cache.

Verify a release

The checksum proves file integrity but not publisher identity. Tagged releases also include signed Sigstore provenance generated by the release workflow. After checking the repository and release tag, verify an AppImage with the GitHub CLI:

gh attestation verify AutoFirma-1.9.2-x86_64.AppImage \
  --repo mbotezatu/autofirma-appimage \
  --signer-workflow mbotezatu/autofirma-appimage/.github/workflows/release.yml \
  --source-ref refs/tags/v1.9.2-1 \
  --deny-self-hosted-runners

Known limitations

• The build currently targets x86_64 Linux only.
• AutoFirma's Swing interface requires X11 or XWayland.
• Desktop integration and browser certificate trust are not automated.
• An AppImage is a portable package, not a security sandbox.

License

The packaging code is available under the MIT License.

The bundled AutoFirma application is distributed by the Spanish Government under EUPL-1.1 or GPL-2.0-or-later. Its license texts are included under /usr/share/doc/autofirma/ inside the AppImage.

The bundled Eclipse Temurin runtime is licensed under GPL-2.0-with-Classpath-Exception and retains its component notices in the runtime's legal/ directory.