How to Sign and Verify Files with Minisign

A digital signature lets someone check whether a file matches what its signer approved. Minisign creates a small, separate signature file that recipients verify using a public key. It is useful for software archives, scripts, and configuration bundles. Signing does not encrypt the contents, and a valid signature does not establish that the contents are safe to run.

Requirements

Use Ubuntu 24.04 and an account with sudo access to install Minisign. Signing and verification run as an ordinary user. The publisher needs a private signing key; recipients need only its public counterpart. Keep the private key on a controlled machine, outside any website’s download directory.

1. Install Minisign

Install the distribution package on the signing machine and any Linux machine that will verify files:

$ sudo apt update
$ sudo apt install minisign
$ minisign -v

Create a working directory for the archive and public files:

$ mkdir minisign-release
$ cd minisign-release
$ umask 077

Use a different directory name if this one already exists. The restrictive umask protects newly created files while you work; adjust permissions only on public artifacts when publishing them. It does not change permissions on files that already exist.

2. Generate the signing keys

Prepare the private-key directory:

$ mkdir -p ~/.minisign
$ chmod 700 ~/.minisign

Choose an unused secret-key filename and generate a pair:

$ minisign -G -p release.pub -s ~/.minisign/release.key

Enter and confirm a strong password at the hidden prompts. Minisign encrypts the secret-key file with that password. Do not add -W, which disables password protection, or -f, which permits overwriting an existing key pair.

The files have different purposes:

• ~/.minisign/release.key is the private signing key. Keep it secret and retain a protected backup.
• release.pub is the public verification key. Share it with recipients through an authenticated channel.

Restrict the secret-key file explicitly:

$ chmod 600 ~/.minisign/release.key

Generate this pair once for the publishing identity, not once for every release. Reusing the public key lets recipients recognize later releases without accepting a new trust anchor each time. If you lose the secret key or its password, you cannot sign new files with that identity; existing signatures remain verifiable.

If the private key is exposed, stop using it for new releases and notify recipients through your established channel. Password protection reduces the risk from a stolen key file, but it does not protect a key that is unlocked on a compromised signing machine.

3. Prepare and sign the archive

For a simple example, create release.txt in the working directory with these contents:

Release 1.0
Configuration bundle for the application.

Build the archive, or substitute an existing finished file:

$ tar -czf release-1.0.tar.gz release.txt

Sign the final archive and attach a meaningful trusted comment:

$ minisign -Sm release-1.0.tar.gz -s ~/.minisign/release.key -t 'release-1.0.tar.gz version 1.0'

Enter the secret-key password when prompted. The command creates release-1.0.tar.gz.minisig beside the archive. Minisign does not modify the archive when signing it. If you rebuild, recompress, or otherwise change that file afterward, sign the replacement and distribute the matching signature.

The signature authenticates file contents, not their location on disk. Renaming an unchanged archive does not invalidate its signature. The signed comment helps recipients identify the intended release, but Minisign does not automatically enforce version numbers or reject an older, correctly signed release.

Use versioned artifact names and retain each archive with its corresponding signature. Replacing an old download while keeping its old signature creates a broken pair. Finish any release-building steps before signing, then copy those exact bytes to the download location.

4. Establish trust before distributing files

Give recipients the archive and its .minisig file. They must also obtain the authentic public key. Publish the key through an established, authenticated project channel, confirm it directly with the publisher, or compare it with a previously trusted copy.

Downloading a replacement public key from the same untrusted location as a suspicious archive proves nothing: an attacker could replace the archive, signature, and key together. Do not accept a changed key merely because verification succeeds with it. Confirm a key change using an already trusted channel before using it for verification.

If you need a download host, an InterServer VPS can serve the public archive and signature. Upload only the public artifacts, never release.key. Keep a private backup of the signing key separate from the downloadable release files.

When publishing through a web server, public files must be readable by the account serving them. Check that requirement without weakening the permissions on the signing-key directory. A signature needs no special server-side processing; it is an ordinary downloadable file.

5. Verify the downloaded archive

On the recipient’s machine, place the downloaded archive and signature in a working directory. Put the independently authenticated public key in release.pub, then run:

$ minisign -Vm release-1.0.tar.gz -p release.pub

By default, Minisign looks for release-1.0.tar.gz.minisig. Successful verification reports that the signature and comment signature are verified, then displays the trusted comment. Check that the comment describes the release you intended to obtain.

If the signature has a different filename, supply it explicitly:

$ minisign -Vm release-1.0.tar.gz -p release.pub -x release-1.0.tar.gz.minisig

Verification does not require the secret key, its password, or a network connection once these files are available. The verification command leaves the archive unchanged. Keep the verified copy protected from modification until you use it; checking one file and then replacing it defeats the purpose.

6. Stop processing when verification fails

Minisign returns zero for successful verification and a nonzero status for failure. In a shell workflow, use && to perform the next action only after success. For example, list archive members only when verification passes:

$ minisign -Vm release-1.0.tar.gz -p release.pub && tar -tzf release-1.0.tar.gz

Do not hide verification errors with || true or treat the presence of a signature file as success. If verification fails, do not install or distribute that copy as verified.

Troubleshooting

Signature verification failed: obtain a fresh archive and its matching signature. Check that neither was edited or paired with another release. Repacking an archive can change its bytes even when its extracted files appear identical.

Public key mismatch: confirm the full public key against a trusted source. Do not replace it with an arbitrary key just to clear the error.

Missing signature: check the expected .minisig filename or specify its actual path with -x.

Incorrect signing password: retry the password for this secret key. Generating a new pair will not recover the old identity.

A signature comment changed: Minisign signatures contain both trusted and untrusted comments. The trusted comment is authenticated; the untrusted comment is not. Never use the untrusted line to decide who signed a file or which release you should install.